FLTK 1.4.0
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.

Determining the Goals of the Text Editor

As our first step, we define what we want our text editor to do:

  1. Edit a single text document.
  2. Provide a menubar/menus for all functions.
  3. Load from a file.
  4. Save to a file.
  5. Keep track of when the file has been changed.
  6. Cut/copy/delete/paste menus.
  7. Search and replace functionality.
  8. Multiple views of the same text.
  9. "C" language syntax highlighting.

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.

#include <FL/Fl_Double_Window.H>
#include <FL/Fl.H>
Fl_Double_Window *app_window = NULL;
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();
}
Fl static class.
The Fl_Double_Window provides a double-buffered window.
Definition: Fl_Double_Window.H:31
void show() FL_OVERRIDE
Makes a widget visible.
Definition: Fl_Double_Window.cxx:45
static int run()
Calls Fl::wait()repeatedly as long as any windows are displayed.
Definition: Fl.cxx:649

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.

For Linux and macOS, FLTK comes with the fltk-config script that generates the compiler commands for you:

fltk-config --compile editor.cxx

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.

Chapter 2: Adding a Menu Bar

In this chapter, we will handle the window title and add the main menu bar with a File menu and a Quit button.

We need to declare a variable to track track changes in the text, and a buffer for the current filename.

// remove `main()` from chapter 1, but keep the rest of the code, then add...
#include <FL/Fl_Menu_Bar.H>
#include <FL/fl_ask.H>
#include <FL/filename.H>
Fl_Menu_Bar *app_menu_bar = NULL;
bool text_changed = false;
char app_filename[FL_PATH_MAX] = "";
This widget provides a standard menubar interface.
Definition: Fl_Menu_Bar.H:65
File names and URI utility functions.
API for common dialogs.
Public header for FLTK's platform-agnostic string handling.
#define FL_PATH_MAX
all path buffers should use this length
Definition: filename.H:45

The window title is either "FLTK Editor" if the text is not saved in any file, or the filename, followed by an * if the text changed. Note that we have two ways to set the label of a widget. label() will link a static text, and copy_label() which will copy and manage the label text.

void update_title() {
const char *fname = NULL;
if (app_filename[0])
fname = fl_filename_name(app_filename);
if (fname) {
char buf[FL_PATH_MAX + 3];
if (text_changed) {
snprintf(buf, FL_PATH_MAX+2, "%s *", fname);
} else {
snprintf(buf, FL_PATH_MAX+2, "%s", fname);
}
app_window->copy_label(buf);
} else {
app_window->label("FLTK Editor");
}
}
void copy_label(const char *a)
Sets the window titlebar label to a copy of a character string.
Definition: Fl_Window.cxx:159
const char * label() const
See void Fl_Window::label(const char*)
Definition: Fl_Window.H:357
const char * fl_filename_name(const char *filename)
Gets the file name from a path.
Definition: Fl.cxx:2184

Now instead of writing directly to text_changed, we write a function that can set and clear the flag, and update the title accordingly.

void set_changed(bool v) {
if (v != text_changed) {
text_changed = v;
update_title();
}
}

Let's do the same for changing the filename. If the new filename is NULL, the window title will revert to "FLTK Editor".

void set_filename(const char *new_filename) {
if (new_filename) {
fl_strlcpy(app_filename, new_filename, FL_PATH_MAX);
} else {
app_filename[0] = 0;
}
update_title();
}

But enough of managing window titles. The following code will add the first widget to our window. A menubar is created at the top and all across the main window.

void menu_quit_callback(Fl_Widget *, void *) { /* TODO */ }
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();
}
int main (int argc, char **argv) {
tut1_build_app_window();
tut2_build_app_menu_bar();
app_window->show(argc, argv);
return Fl::run();
}
void end()
Exactly the same as current(this->parent()).
Definition: Fl_Group.cxx:73
void begin()
Sets the current group so you can build the widget tree by just constructing the widgets.
Definition: Fl_Group.cxx:67
int add(const char *, int shortcut, Fl_Callback *, void *=0, int=0)
Adds a new menu item.
Definition: Fl_Menu_add.cxx:348
Fl_Widget is the base class for all widgets in FLTK.
Definition: Fl_Widget.H:104
Fl_Callback_p callback() const
Gets the current callback function for the widget.
Definition: Fl_Widget.H:701
void w(int v)
Internal use only.
Definition: Fl_Widget.H:146
#define FL_COMMAND
An alias for FL_CTRL on Windows and X11, or FL_META on MacOS X.
Definition: platform_types.h:75

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.

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.

Our basic callback is simple:

void menu_quit_callback(Fl_Widget *, void *) {
}
static void hide_all_windows()
Hide all visible windows to make FLTK leave Fl::run().
Definition: Fl.cxx:728

Fl::hide_all_windows() will make all windows invisible, causing Fl::run() to return and main to exit.

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.

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:

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;
}
}
int fl_choice(const char *fmt, const char *b0, const char *b1, const char *b2,...)
Shows a dialog displaying the printf style fmt message.
Definition: fl_ask.cxx:217

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.

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.

#include <FL/Fl_Text_Buffer.H>
#include <FL/Fl_Text_Editor.H>
Fl_Text_Editor *app_editor = NULL;
Fl_Text_Editor *app_split_editor = NULL; // for later
Fl_Text_Buffer *app_text_buffer = NULL;
// ... 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();
}
const Fl_Font FL_COURIER
Courier normal.
Definition: Enumerations.H:1052
void resizable(Fl_Widget &o)
Sets the group's resizable widget.
Definition: Fl_Group.H:144
This class manages Unicode text displayed in one or more Fl_Text_Display widgets.
Definition: Fl_Text_Buffer.H:201
void add_modify_callback(Fl_Text_Modify_Cb bufModifiedCB, void *cbArg)
Adds a callback function that is called whenever the text buffer is modified.
Definition: Fl_Text_Buffer.cxx:884
void buffer(Fl_Text_Buffer *buf)
Attach a text buffer to display, replacing the current buffer (if any).
Definition: Fl_Text_Display.cxx:367
Fl_Font textfont() const
Gets the default font used when drawing text in the widget.
Definition: Fl_Text_Display.H:363
This is the FLTK text editor widget.
Definition: Fl_Text_Editor.H:38
void h(int v)
Internal use only.
Definition: Fl_Widget.H:148

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.

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:

// 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)
set_changed(true);
}

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.

// insert before tut3_build_main_editor()
void menu_new_callback(Fl_Widget*, void*) {
app_text_buffer->text("");
set_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);
...
int insert(int index, const char *, int shortcut, Fl_Callback *, void *=0, int=0)
Inserts a new menu item at the specified index position.
Definition: Fl_Menu_add.cxx:384
int find_index(const char *name) const
Find the menu item index for a given menu pathname, such as "Edit/Copy".
Definition: Fl_Menu_.cxx:218
char * text() const
Get a copy of the entire contents of the text buffer.
Definition: Fl_Text_Buffer.cxx:261

Chapter 4: Reading and Writing Files

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.

#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);
}
@ FL_MENU_DIVIDER
Creates divider line below this item. Also ends a group of radio buttons.
Definition: Fl_Menu_Item.H:36
Fl_Native_File_Chooser widget.
Note
The menu shortcuts FL_COMMAND+'s' and FL_COMMAND+'S' look the same at a first glance, but the second shortcut is actually Ctrl-Shift-S due to the capital letter 'S'. Also, we use FL_COMMAND as our menu shortcut modifier key. FL_COMMAND translates to FL_CTRL on Windows and Linux, and to FL_META on macOS, better known as the cloverleaf, or simply "the Apple key".

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.

void menu_save_as_callback(Fl_Widget*, void*) {
Fl_Native_File_Chooser file_chooser;
file_chooser.title("Save File As...");
if (file_chooser.show() == 0) {
app_text_buffer->savefile(file_chooser.filename());
set_filename(file_chooser.filename());
set_changed(false);
}
}
This class lets an FLTK application easily and consistently access the operating system's native file...
Definition: Fl_Native_File_Chooser.H:130
void title(const char *t)
Set the title of the file chooser's dialog window.
Definition: Fl_Native_File_Chooser.cxx:137
void type(int t)
Sets the current Fl_Native_File_Chooser::Type of browser.
Definition: Fl_Native_File_Chooser.cxx:35
const char * filename() const
Return the filename the user chose.
Definition: Fl_Native_File_Chooser.cxx:94
@ BROWSE_SAVE_FILE
browse to save a file
Definition: Fl_Native_File_Chooser.H:139
int show()
Post the chooser's dialog.
Definition: Fl_Native_File_Chooser.cxx:265
int savefile(const char *file, int buflen=128 *1024)
Saves a text file from the current buffer.
Definition: Fl_Text_Buffer.H:410

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

// insert before `if (file_chooser.show()...`
if (app_filename[0]) {
char temp_filename[FL_PATH_MAX];
fl_strlcpy(temp_filename, app_filename, FL_PATH_MAX);
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);
}
}
void directory(const char *val)
Preset the directory the browser will show when opened.
Definition: Fl_Native_File_Chooser.cxx:121
void preset_file(const char *f)
Sets the default filename for the chooser.
Definition: Fl_Native_File_Chooser.cxx:238

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.

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());
set_changed(false);
}
}

Now that we have a save method available, we can improve the menu_quit_callback and offer the option to save the current modified text before quitting the app. Here is the new quit callback code that replaces the old callback:

void menu_quit_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 == 0) // cancel
return;
if (r == 1) { // save
menu_save_callback(NULL, NULL);
return;
}
}
}

On to loading a new file. Let's write the function to load a file from a given file name:

void load(const char *filename) {
if (app_text_buffer->loadfile(filename) == 0) {
set_filename(filename);
set_changed(false);
}
}
int loadfile(const char *file, int buflen=128 *1024)
Loads a text file into the buffer.
Definition: Fl_Text_Buffer.H:385

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.

void load(const char *filename) {
if (app_text_buffer->loadfile(filename) == 0) {
set_filename(filename);
set_changed(false);
} else {
fl_alert("Failed to load file\n%s\n%s",
filename,
strerror(errno));
}
}
void fl_alert(const char *fmt,...)
Shows an alert message dialog box.
Definition: fl_ask.cxx:122

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:

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();
}
...

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.

...
Fl_Native_File_Chooser file_chooser;
file_chooser.title("Open File...");
...
@ BROWSE_FILE
browse files (lets user choose one file)
Definition: Fl_Native_File_Chooser.H:135

Again, we preload the file chooser with the last used path and file name:

...
if (app_filename[0]) {
char temp_filename[FL_PATH_MAX];
fl_strlcpy(temp_filename, app_filename, FL_PATH_MAX);
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);
}
}
...

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:

if (file_chooser.show() == 0)
load(file_chooser.filename());
}

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:

// ... 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);
}

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.

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.

// ... 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);
app_window->show(argc, argv);
return Fl::run();
}
static int args(int argc, char **argv, int &i, Fl_Args_Handler cb=0)
Parse command line switches using the cb argument handler.
Definition: Fl_arg.cxx:276
static int args_to_utf8(int argc, char **&argv)
Convert Windows commandline arguments to UTF-8.
Definition: Fl.cxx:2461
void fl_open_callback(void(*cb)(const char *))
Register a function called for each file dropped onto an application icon.
Definition: Fl.cxx:2315

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

int args_handler(int argc, char **argv, int &i) {
if (argv && argv[i] && argv[i][0]!='-') {
load(argv[i]);
i++;
return 1;
}
return 0;
}

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.

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:

void menu_cut_callback(Fl_Widget*, void* v) {
if (e && (e == app_editor || e == app_split_editor))
}
static int kf_cut(int c, Fl_Text_Editor *e)
Does a cut of selected text in the current buffer of editor 'e'.
Definition: Fl_Text_Editor.cxx:568
static Fl_Widget * focus()
Gets the current Fl::focus() widget.
Definition: Fl.H:866

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:

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);
}

Chapter 6: Find and Find Next

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.

void find_next(const char *needle) {
Fl_Text_Editor *editor = app_editor;
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) {
app_text_buffer->select(pos, pos + (int)strlen(needle));
editor->insert_position(pos + (int)strlen(needle));
} else {
fl_alert("No further occurrences of '%s' found!", needle);
}
}
void select(int start, int end)
Selects a range of characters in the buffer.
Definition: Fl_Text_Buffer.cxx:717
int search_forward(int startPos, const char *searchString, int *foundPos, int matchCase=0) const
Search forwards in buffer for string searchString, starting with the character startPos,...
Definition: Fl_Text_Buffer.cxx:1248
void insert_position(int newPos)
Sets the position of the text insertion cursor for text display.
Definition: Fl_Text_Display.cxx:859
void show_insert_position()
Scrolls the text buffer to show the current insert position.
Definition: Fl_Text_Display.cxx:1290

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.

char last_find_text[1024] = "";
void menu_find_callback(Fl_Widget*, void* v) {
const char *find_text = fl_input("Find in text:", last_find_text);
if (find_text) {
fl_strlcpy(last_find_text, find_text, sizeof(last_find_text));
find_next(find_text);
}
}
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);
}
}

And of course we need to add two menu items to our main application menu.

...
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);
...

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:

char last_replace_text[1024] = "";
void replace_selection(const char *new_text) {
Fl_Text_Editor *editor = app_editor;
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));
}
}
void insert(int pos, const char *text, int insertedLength=-1)
Inserts null-terminated string text at position pos.
Definition: Fl_Text_Buffer.cxx:383
void remove_selection()
Removes the text in the primary selection.
Definition: Fl_Text_Buffer.cxx:762
int selection_position(int *start, int *end)
Gets the selection position.
Definition: Fl_Text_Buffer.cxx:744

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.

The Replace_Dialog class

The Replace_Dialog class holds pointers to our active UI elements as well as all the callbacks for the dialog buttons.

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*);
};
Replace_Dialog *replace_dialog = NULL;
Buttons generate callbacks when they are clicked by the user.
Definition: Fl_Button.H:76
This is the FLTK text input widget.
Definition: Fl_Input.H:220
#define FL_OVERRIDE
This macro makes it safe to use the C++11 keyword override with older compilers.
Definition: fl_attr.h:46

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:

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();
}
Fl_Flex is a container (layout) widget for one row or one column of widgets.
Definition: Fl_Flex.H:114
int gap() const
Return the gap size of the widget.
Definition: Fl_Flex.H:293
int margin() const
Returns the left margin size of the widget.
Definition: Fl_Flex.H:214
virtual void end()
Ends automatic child addition and resizes all children.
Definition: Fl_Flex.cxx:280
@ HORIZONTAL
horizontal layout (one row)
Definition: Fl_Flex.H:130
uchar type() const
Gets the widget type.
Definition: Fl_Widget.H:343

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.

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.

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().

void Replace_Dialog::show() {
find_text_input->value(last_find_text);
replace_text_input->value(last_replace_text);
}
int value(const char *)
Changes the widget text.
Definition: Fl_Input_.cxx:1461

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);.

The callback itself can then extract the this pointer with a static cast:

void Replace_Dialog::close_callback(Fl_Widget*, void* my_dialog) {
Replace_Dialog *dlg = static_cast<Replace_Dialog*>(my_dialog);
dlg->hide();
}

The callback for the Find button uses our already implemented find_next function:

void Replace_Dialog::find_next_callback(Fl_Widget*, void* my_dialog) {
Replace_Dialog *dlg = static_cast<Replace_Dialog*>(my_dialog);
fl_strlcpy(last_find_text, dlg->find_text_input->value(), sizeof(last_find_text));
fl_strlcpy(last_replace_text, dlg->replace_text_input->value(), sizeof(last_replace_text));
if (last_find_text[0])
find_next(last_find_text);
}

The Replace button callback calls our newly implemented replace_selection function and then continues on to the find_next_callback:

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);
}

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:

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);
}

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:

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);
}
@ FL_MENU_TOGGLE
Item is a checkbox toggle (shows checkbox for on/off state)
Definition: Fl_Menu_Item.H:30

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:

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();
}
const Fl_Menu_Item * mvalue() const
Return a pointer to the last menu item that was picked.
Definition: Fl_Menu_.H:162
void linenumber_width(int width)
Set width of screen area for line numbers.
Definition: Fl_Text_Display.cxx:236
void redraw()
Schedules the drawing of the widget.
Definition: Fl.cxx:1659
The Fl_Menu_Item structure defines a single menu item that is used by the Fl_Menu_ class.
Definition: Fl_Menu_Item.H:115
int value() const
Returns the current value of the check or radio item.
Definition: Fl_Menu_Item.H:406

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.

Let's not forget to update the line number display for a potential split editor widget es well:

// 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();
}

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.

Chapter 9: Split 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.

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.

#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);
void remove(int index)
Removes the widget at index from the group but does not delete it.
Definition: Fl_Group.cxx:583
The Fl_Tile class lets you resize its children by dragging the border between them.
Definition: Fl_Tile.H:27

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().

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.
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();
void add(Fl_Widget &)
The widget is removed from its current group (if any) and then added to the end of this group.
Definition: Fl_Group.cxx:558
virtual void hide()
Makes a widget invisible.
Definition: Fl_Widget.cxx:261
void x(int v)
Internal use only.
Definition: Fl_Widget.H:142
void y(int v)
Internal use only.
Definition: Fl_Widget.H:144

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.

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+'2', menu_split_callback, NULL, FL_MENU_TOGGLE);
}
void size_range(int index, int minw, int minh, int maxw=0x7FFFFFFF, int maxh=0x7FFFFFFF)
Set the allowed size range for the child at the given index.
Definition: Fl_Tile.cxx:833

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:

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();
}
void init_sizes()
Resets the internal array of widget sizes and positions.
Definition: Fl_Group.cxx:690
void resize(int X, int Y, int W, int H) FL_OVERRIDE
Change the size of the displayed text area.
Definition: Fl_Text_Display.cxx:475
virtual void show()
Makes a widget visible.
Definition: Fl_Widget.cxx:249
void size(int W, int H)
Changes the size of the widget.
Definition: Fl_Widget.H:410

Chapter 10: 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 implementation is based on the excellent NEdit text editor core, from https://sourceforge.net/projects/nedit/, 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>:

struct Style_Table_Entry {
Fl_Color color;
Fl_Font font;
int size;
unsigned attr;
};
int Fl_Font
A font number is an index into the internal font table.
Definition: Enumerations.H:1046
unsigned int Fl_Color
An FLTK color value; see also Colors
Definition: Enumerations.H:1103

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:

Fl_Text_Display::Style_Table_Entry styletable[] = { // Style table
{ FL_BLACK, FL_COURIER, FL_NORMAL_SIZE }, // A - Plain
{ FL_DARK_GREEN, FL_COURIER_ITALIC, FL_NORMAL_SIZE }, // B - Line comments
{ FL_DARK_GREEN, FL_COURIER_ITALIC, FL_NORMAL_SIZE }, // C - Block comments
{ FL_BLUE, FL_COURIER, FL_NORMAL_SIZE }, // D - Strings
{ FL_DARK_RED, FL_COURIER, FL_NORMAL_SIZE }, // E - Directives
{ FL_DARK_RED, FL_COURIER_BOLD, FL_NORMAL_SIZE }, // F - Types
{ FL_BLUE, FL_COURIER_BOLD, FL_NORMAL_SIZE } // G - Keywords
};
const Fl_Font FL_COURIER_BOLD
Courier bold.
Definition: Enumerations.H:1053
Fl_Fontsize FL_NORMAL_SIZE
normal font size
Definition: Fl_Widget.cxx:107
const Fl_Font FL_COURIER_ITALIC
Courier italic.
Definition: Enumerations.H:1054
This structure associates the color, font, and font size of a string to draw with an attribute mask m...
Definition: Fl_Text_Display.H:145

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:

Fl_Text_Buffer *app_style_buffer;
app_editor->highlight_data(app_style_buffer, styletable,
sizeof(styletable) / sizeof(styletable[0]),
'A', style_unfinished_cb, 0);
void highlight_data(Fl_Text_Buffer *styleBuffer, const Style_Table_Entry *styleTable, int nStyles, char unfinishedStyle, Unfinished_Style_Cb unfinishedHighlightCB, void *cbArg)
Attach (or remove) highlight information in text display and redisplay.
Definition: Fl_Text_Display.cxx:438

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:

app_text_buffer->add_modify_callback(style_update, app_editor);

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:

//
// 'style_update()' - Update the style buffer...
//
void
style_update(int pos, // I - Position of update
int nInserted, // I - Number of inserted chars
int nDeleted, // I - Number of deleted chars
int nRestyled, // I - Number of restyled chars
const char *deletedText, // I - Text that was deleted
void *cbArg) { // I - Callback data
int start, // Start of text
end; // End of text
char last, // Last style on line
*style, // Style data
*text; // Text data
// If this is just a selection change, just unselect the style buffer...
if (nInserted == 0 && nDeleted == 0) {
app_style_buffer->unselect();
return;
}
// Track changes in the text buffer...
if (nInserted > 0) {
// Insert characters into the style buffer...
style = new char[nInserted + 1];
memset(style, 'A', nInserted);
style[nInserted] = '\0';
app_style_buffer->replace(pos, pos + nDeleted, style);
delete[] style;
} else {
// Just delete characters in the style buffer...
app_style_buffer->remove(pos, pos + nDeleted);
}
// Select the area that was just updated to avoid unnecessary
// callbacks...
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 = 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);
app_style_buffer->replace(start, end, style);
((Fl_Text_Editor *)cbArg)->redisplay_range(start, end);
if (last != style[end - start - 1]) {
// The last character on the line changed styles, so reparse the
// remainder of the buffer...
free(text);
free(style);
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);
app_style_buffer->replace(start, end, style);
((Fl_Text_Editor *)cbArg)->redisplay_range(start, end);
}
free(text);
free(style);
}
int length() const
Returns the number of bytes in the buffer.
Definition: Fl_Text_Buffer.H:223
void unselect()
Cancels any previous selection on the primary text selection object.
Definition: Fl_Text_Buffer.cxx:732
void replace(int start, int end, const char *text, int insertedLength=-1)
Deletes the characters between start and end, and inserts the null-terminated string text in their pl...
Definition: Fl_Text_Buffer.cxx:457
char * text_range(int start, int end) const
Get a copy of a part of the text buffer.
Definition: Fl_Text_Buffer.cxx:314
void remove(int start, int end)
Deletes a range of characters in the buffer.
Definition: Fl_Text_Buffer.cxx:485
int line_end(int pos) const
Finds and returns the position of the end of the line containing position pos (which is either a poin...
Definition: Fl_Text_Buffer.cxx:1053
int line_start(int pos) const
Returns the position of the start of the line containing position pos.
Definition: Fl_Text_Buffer.cxx:1042

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:

//
// 'style_parse()' - Parse text and produce style data.
//
void
style_parse(const char *text,
char *style,
int length) {
char current;
int col;
int last;
char buf[255],
*bufptr;
const char *temp;
for (current = *style, col = 0, last = 0; length > 0; length --, text ++) {
if (current == 'A') {
// Check for directives, comments, strings, and keywords...
if (col == 0 && *text == '#') {
// Set style to directive
current = 'E';
} else if (strncmp(text, "//", 2) == 0) {
current = 'B';
} else if (strncmp(text, "/*", 2) == 0) {
current = 'C';
} else if (strncmp(text, "\\\"", 2) == 0) {
// Quoted quote...
*style++ = current;
*style++ = current;
text ++;
length --;
col += 2;
continue;
} else if (*text == '\"') {
current = 'D';
} else if (!last && islower(*text)) {
// Might be a keyword...
for (temp = text, bufptr = buf;
islower(*temp) && bufptr < (buf + sizeof(buf) - 1);
*bufptr++ = *temp++);
if (!islower(*temp)) {
*bufptr = '\0';
bufptr = buf;
if (bsearch(&bufptr, code_types,
sizeof(code_types) / sizeof(code_types[0]),
sizeof(code_types[0]), compare_keywords)) {
while (text < temp) {
*style++ = 'F';
text ++;
length --;
col ++;
}
text --;
length ++;
last = 1;
continue;
} else if (bsearch(&bufptr, code_keywords,
sizeof(code_keywords) / sizeof(code_keywords[0]),
sizeof(code_keywords[0]), compare_keywords)) {
while (text < temp) {
*style++ = 'G';
text ++;
length --;
col ++;
}
text --;
length ++;
last = 1;
continue;
}
}
}
} else if (current == 'C' && strncmp(text, "*/", 2) == 0) {
// Close a C comment...
*style++ = current;
*style++ = current;
text ++;
length --;
current = 'A';
col += 2;
continue;
} else if (current == 'D') {
// Continuing in string...
if (strncmp(text, "\\\"", 2) == 0) {
// Quoted end quote...
*style++ = current;
*style++ = current;
text ++;
length --;
col += 2;
continue;
} else if (*text == '\"') {
// End quote...
*style++ = current;
col ++;
current = 'A';
continue;
}
}
// Copy style info...
if (current == 'A' && (*text == '{' || *text == '}')) *style++ = 'G';
else *style++ = current;
col ++;
last = isalnum(*text) || *text == '.';
if (*text == '\n') {
// Reset column and possibly reset the style
col = 0;
if (current == 'B' || current == 'E') current = 'A';
}
}
}


[Prev] How Does Resizing Work? [Index] Drawing Things in FLTK [Next]