FLTK 1.4.4

Loading...
Searching...
No Matches
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.H
Fl static class.
Fl_Double_Window
The Fl_Double_Window provides a double-buffered window.
Definition Fl_Double_Window.H:31
Fl_Double_Window::show
void show() FL_OVERRIDE
Makes a widget visible.
Definition Fl_Double_Window.cxx:45
Fl::run
static int run()
Calls Fl::wait()repeatedly as long as any windows are displayed.
Definition Fl.cxx:651

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>
#include <FL/fl_string_functions.h>
Fl_Menu_Bar *app_menu_bar = NULL;
bool text_changed = false;
char app_filename[FL_PATH_MAX] = "";
filename.H
File names and URI utility functions.
fl_ask.H
API for common dialogs.
fl_string_functions.h
Public header for FLTK's platform-agnostic string handling.
FL_PATH_MAX
#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];
buf[FL_PATH_MAX + 2] = '\0'; // ensure that the buffer is always terminated
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");
}
}
Fl_Window::copy_label
void copy_label(const char *a)
Sets the window titlebar label to a copy of a character string.
Definition Fl_Window.cxx:159
Fl_Window::label
const char * label() const
See void Fl_Window::label(const char*).
Definition Fl_Window.H:367
fl_filename_name
const char * fl_filename_name(const char *filename)
Gets the file name from a path.
Definition Fl.cxx:2193

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();
}
Fl_Group::end
void end()
Exactly the same as current(this->parent()).
Definition Fl_Group.cxx:73
Fl_Group::begin
void begin()
Sets the current group so you can build the widget tree by just constructing the widgets.
Definition Fl_Group.cxx:67
Fl_Widget
Fl_Widget is the base class for all widgets in FLTK.
Definition Fl_Widget.H:112
Fl_Widget::callback
Fl_Callback_p callback() const
Gets the current callback function for the widget.
Definition Fl_Widget.H:740
Fl_Widget::w
void w(int v)
Internal use only.
Definition Fl_Widget.H:154
FL_COMMAND
#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 *) {
Fl::hide_all_windows();
}
Fl::hide_all_windows
static void hide_all_windows()
Hide all visible windows to make FLTK leave Fl::run().
Definition Fl.cxx:730

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;
}
Fl::hide_all_windows();
}

# 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();
}
FL_COURIER
const Fl_Font FL_COURIER
Courier normal.
Definition Enumerations.H:1069
Fl_Group::resizable
void resizable(Fl_Widget &o)
Sets the group's resizable widget.
Definition Fl_Group.H:156
Fl_Text_Buffer
This class manages Unicode text displayed in one or more Fl_Text_Display widgets.
Definition Fl_Text_Buffer.H:201
Fl_Text_Buffer::add_modify_callback
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
Fl_Text_Display::buffer
void buffer(Fl_Text_Buffer *buf)
Attach a text buffer to display, replacing the current buffer (if any).
Definition Fl_Text_Display.cxx:369
Fl_Text_Display::textfont
Fl_Font textfont() const
Gets the default font used when drawing text in the widget.
Definition Fl_Text_Display.H:363
Fl_Text_Editor
This is the FLTK text editor widget.
Definition Fl_Text_Editor.H:38
Fl_Widget::h
void h(int v)
Internal use only.
Definition Fl_Widget.H:156

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);
...
Fl_Text_Buffer::text
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/Fl_Native_File_Chooser.H>
#include <FL/platform.H>
#include <errno.h>
// ... add callbacks here
void tut4_add_file_support() {
int ix = app_menu_bar->find_index(menu_quit_callback);
app_menu_bar->insert(ix, "Open", FL_COMMAND+'o', menu_open_callback, NULL, FL_MENU_DIVIDER);
app_menu_bar->insert(ix+1, "Save", FL_COMMAND+'s', menu_save_callback);
app_menu_bar->insert(ix+2, "Save as...", FL_COMMAND+'S', menu_save_as_callback, NULL, FL_MENU_DIVIDER);
}
Fl_Native_File_Chooser.H
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...");
file_chooser.type(Fl_Native_File_Chooser::BROWSE_SAVE_FILE);
if (file_chooser.show() == 0) {
app_text_buffer->savefile(file_chooser.filename());
set_filename(file_chooser.filename());
set_changed(false);
}
}
Fl_Native_File_Chooser
This class lets an FLTK application easily and consistently access the operating system's native file...
Definition Fl_Native_File_Chooser.H:130
Fl_Native_File_Chooser::title
void title(const char *t)
Set the title of the file chooser's dialog window.
Definition Fl_Native_File_Chooser.cxx:137
Fl_Native_File_Chooser::type
void type(int t)
Sets the current Fl_Native_File_Chooser::Type of browser.
Definition Fl_Native_File_Chooser.cxx:35
Fl_Native_File_Chooser::filename
const char * filename() const
Return the filename the user chose.
Definition Fl_Native_File_Chooser.cxx:94
Fl_Native_File_Chooser::BROWSE_SAVE_FILE
@ BROWSE_SAVE_FILE
browse to save a file
Definition Fl_Native_File_Chooser.H:139
Fl_Native_File_Chooser::show
int show()
Post the chooser's dialog.
Definition Fl_Native_File_Chooser.cxx:265
Fl_Text_Buffer::savefile
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);
}
}
Fl_Native_File_Chooser::directory
void directory(const char *val)
Preset the directory the browser will show when opened.
Definition Fl_Native_File_Chooser.cxx:121
Fl_Native_File_Chooser::preset_file
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;
}
}
Fl::hide_all_windows();
}

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);
}
}
Fl_Text_Buffer::loadfile
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));
}
}

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...");
file_chooser.type(Fl_Native_File_Chooser::BROWSE_FILE);
...
Fl_Native_File_Chooser::BROWSE_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);
fl_open_callback(load);
app_window->show(argc, argv);
return Fl::run();
}
Fl::args
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
Fl::args_to_utf8
static int args_to_utf8(int argc, char **&argv)
Convert Windows commandline arguments to UTF-8.
Definition Fl.cxx:2514
fl_open_callback
void fl_open_callback(void(*cb)(const char *))
Register a function called for each file dropped onto an application icon.
Definition Fl.cxx:2332

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) {
Fl_Widget *e = Fl::focus();
if (e && (e == app_editor || e == app_split_editor))
Fl_Text_Editor::kf_cut(0, (Fl_Text_Editor*)e);
}
Fl_Text_Editor::kf_cut
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
Fl::focus
static Fl_Widget * focus()
Gets the current Fl::focus() widget.
Definition Fl.H:883

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;
Fl_Widget *e = Fl::focus();
if (e && e == app_split_editor)
editor = app_split_editor;
int pos = editor->insert_position();
int found = app_text_buffer->search_forward(pos, needle, &pos);
if (found) {
app_text_buffer->select(pos, pos + (int)strlen(needle));
editor->insert_position(pos + (int)strlen(needle));
editor->show_insert_position();
} else {
fl_alert("No further occurrences of '%s' found!", needle);
}
}
Fl_Text_Buffer::select
void select(int start, int end)
Selects a range of characters in the buffer.
Definition Fl_Text_Buffer.cxx:717
Fl_Text_Buffer::search_forward
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:1290
Fl_Text_Display::insert_position
void insert_position(int newPos)
Sets the position of the text insertion cursor for text display.
Definition Fl_Text_Display.cxx:873
Fl_Text_Display::show_insert_position
void show_insert_position()
Scrolls the text buffer to show the current insert position.
Definition Fl_Text_Display.cxx:1304

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;
Fl_Widget *e = Fl::focus();
if (e && e == app_split_editor)
editor = app_split_editor;
int start, end;
if (app_text_buffer->selection_position(&start, &end)) {
app_text_buffer->remove_selection();
app_text_buffer->insert(start, new_text);
app_text_buffer->select(start, start + (int)strlen(new_text));
editor->insert_position(start + (int)strlen(new_text));
editor->show_insert_position();
}
}
Fl_Text_Buffer::insert
void insert(int pos, const char *text, int insertedLength=-1)
Inserts null-terminated string text at position pos.
Definition Fl_Text_Buffer.cxx:383
Fl_Text_Buffer::remove_selection
void remove_selection()
Removes the text in the primary selection.
Definition Fl_Text_Buffer.cxx:762
Fl_Text_Buffer::selection_position
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;
Fl_Button
Buttons generate callbacks when they are clicked by the user.
Definition Fl_Button.H:76
Fl_Input
This is the FLTK text input widget.
Definition Fl_Input.H:220
FL_OVERRIDE
#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
Fl_Flex is a container (layout) widget for one row or one column of widgets.
Definition Fl_Flex.H:114
Fl_Flex::gap
int gap() const
Return the gap size of the widget.
Definition Fl_Flex.H:293
Fl_Flex::margin
int margin() const
Returns the left margin size of the widget.
Definition Fl_Flex.H:214
Fl_Flex::HORIZONTAL
@ HORIZONTAL
horizontal layout (one row)
Definition Fl_Flex.H:130
Fl_Flex::end
virtual void end()
Ends automatic child addition and resizes all children.
Definition Fl_Flex.cxx:280
Fl_Widget::type
uchar type() const
Gets the widget type.
Definition Fl_Widget.H:351

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);
Fl_Double_Window::show();
}
Fl_Input_::value
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);
}

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();
}
Fl_Text_Display::linenumber_width
void linenumber_width(int width)
Set width of screen area for line numbers.
Definition Fl_Text_Display.cxx:238
Fl_Widget::redraw
void redraw()
Schedules the drawing of the widget.
Definition Fl.cxx:1668

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);
Fl_Group::remove
void remove(int index)
Removes the widget at index from the group but does not delete it.
Definition Fl_Group.cxx:585
Fl_Tile
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();
Fl_Group::add
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:560
Fl_Widget::hide
virtual void hide()
Makes a widget invisible.
Definition Fl_Widget.cxx:263
Fl_Widget::x
void x(int v)
Internal use only.
Definition Fl_Widget.H:150
Fl_Widget::y
void y(int v)
Internal use only.
Definition Fl_Widget.H:152

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+'i', menu_split_callback, NULL, FL_MENU_TOGGLE);
}
Fl_Tile::size_range
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:857

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();
}
Fl_Group::init_sizes
void init_sizes()
Resets the internal array of widget sizes and positions.
Definition Fl_Group.cxx:692
Fl_Text_Display::resize
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:477
Fl_Widget::show
virtual void show()
Makes a widget visible.
Definition Fl_Widget.cxx:251
Fl_Widget::size
void size(int W, int H)
Changes the size of the widget.
Definition Fl_Widget.H:418

# 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;
};
Fl_Font
int Fl_Font
A font number is an index into the internal font table.
Definition Enumerations.H:1063
Fl_Color
unsigned int Fl_Color
An FLTK color value; see also Colors.
Definition Enumerations.H:1120

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
};
FL_COURIER_BOLD
const Fl_Font FL_COURIER_BOLD
Courier bold.
Definition Enumerations.H:1070
FL_NORMAL_SIZE
Fl_Fontsize FL_NORMAL_SIZE
normal font size
Definition Fl_Widget.cxx:107
FL_COURIER_ITALIC
const Fl_Font FL_COURIER_ITALIC
Courier italic.
Definition Enumerations.H:1071
Fl_Text_Display::Style_Table_Entry
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);
Fl_Text_Display::highlight_data
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:440

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);
}
Fl_Text_Buffer::length
int length() const
Returns the number of bytes in the buffer.
Definition Fl_Text_Buffer.H:223
Fl_Text_Buffer::unselect
void unselect()
Cancels any previous selection on the primary text selection object.
Definition Fl_Text_Buffer.cxx:732
Fl_Text_Buffer::replace
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
Fl_Text_Buffer::text_range
char * text_range(int start, int end) const
Get a copy of a part of the text buffer.
Definition Fl_Text_Buffer.cxx:314
Fl_Text_Buffer::remove
void remove(int start, int end)
Deletes a range of characters in the buffer.
Definition Fl_Text_Buffer.cxx:485
Fl_Text_Buffer::line_end
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
Fl_Text_Buffer::line_start
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]