From d2d5573bc5e36aeb5419cdedec9bd40d25f892d9 Mon Sep 17 00:00:00 2001 From: Greg Ercolano Date: Wed, 20 Jul 2016 00:55:06 +0000 Subject: Bringing over fix [r11759] from 1.3 current to the porting branch. Fl_Text_Editor documentation mods for kf_xxx functions. (Discussion on fltk.coredev May 29 - 30th 2016) git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3-porting@11827 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- src/Fl_Text_Editor.cxx | 147 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 122 insertions(+), 25 deletions(-) (limited to 'src/Fl_Text_Editor.cxx') diff --git a/src/Fl_Text_Editor.cxx b/src/Fl_Text_Editor.cxx index 3af22aa00..f3167e232 100644 --- a/src/Fl_Text_Editor.cxx +++ b/src/Fl_Text_Editor.cxx @@ -226,7 +226,9 @@ static void kill_selection(Fl_Text_Editor* e) { } } -/** Inserts the text associated with the key */ +/** Inserts the text associated with key \p 'c' in editor \p 'e'. + Honors the current selection and insert/overstrike mode. +*/ int Fl_Text_Editor::kf_default(int c, Fl_Text_Editor* e) { // FIXME: this function is a mess! Fix this! if (!c || (!isprint(c) && c != '\t')) return 0; @@ -241,11 +243,22 @@ int Fl_Text_Editor::kf_default(int c, Fl_Text_Editor* e) { return 1; } -/** Ignores the keypress */ +/** Ignores the key \p 'c' in editor \p 'e'. + This method can be used as a keyboard binding to disable a key + that might otherwise be handled or entered as text. + + An example would be disabling FL_Escape, so that it isn't added + to the buffer when invoked by the user. +*/ int Fl_Text_Editor::kf_ignore(int, Fl_Text_Editor*) { return 0; // don't handle } -/** Does a backspace in the current buffer.*/ + +/** Does a backspace for key \p 'c' in the current buffer of editor \p 'e'. + Any current selection is deleted. + Otherwise, the character left is deleted and the cursor moved. + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_backspace(int, Fl_Text_Editor* e) { if (!e->buffer()->selected() && e->move_left()) { int p1 = e->insert_position(); @@ -259,7 +272,9 @@ int Fl_Text_Editor::kf_backspace(int, Fl_Text_Editor* e) { return 1; } -/** Inserts a newline at the current cursor position */ +/** Inserts a newline for key \p 'c' at the current cursor position in editor \p 'e'. + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_enter(int, Fl_Text_Editor* e) { kill_selection(e); e->insert("\n"); @@ -270,7 +285,19 @@ int Fl_Text_Editor::kf_enter(int, Fl_Text_Editor* e) { } extern void fl_text_drag_me(int pos, Fl_Text_Display* d); -/** Moves the text cursor in the direction indicated by key c.*/ +/** Moves the text cursor in the direction indicated by key \p 'c' in editor \p 'e'. + Supported values for 'c' are currently: + \code + FL_Home -- moves the cursor to the beginning of the current line + FL_End -- moves the cursor to the end of the current line + FL_Left -- moves the cursor left one character + FL_Right -- moves the cursor right one character + FL_Up -- moves the cursor up one line + FL_Down -- moves the cursor down one line + FL_Page_Up -- moves the cursor up one page + FL_Page_Down -- moves the cursor down one page + \endcode +*/ int Fl_Text_Editor::kf_move(int c, Fl_Text_Editor* e) { int i; int selected = e->buffer()->selected(); @@ -308,7 +335,9 @@ int Fl_Text_Editor::kf_move(int c, Fl_Text_Editor* e) { return 1; } -/** Extends the current selection in the direction of key c.*/ +/** Extends the current selection in the direction of key \p 'c' in editor \p 'e'. + \see kf_move() +*/ int Fl_Text_Editor::kf_shift_move(int c, Fl_Text_Editor* e) { kf_move(c, e); fl_text_drag_me(e->insert_position(), e); @@ -319,7 +348,20 @@ int Fl_Text_Editor::kf_shift_move(int c, Fl_Text_Editor* e) { } return 1; } -/** Moves the current text cursor in the direction indicated by control key */ + +/** Moves the current text cursor in the direction indicated by control key \p 'c' in editor \p 'e'. + Supported values for 'c' are currently: + \code + FL_Home -- moves the cursor to the beginning of the document + FL_End -- moves the cursor to the end of the document + FL_Left -- moves the cursor left one word + FL_Right -- moves the cursor right one word + FL_Up -- scrolls up one line, without moving cursor + FL_Down -- scrolls down one line, without moving cursor + FL_Page_Up -- moves the cursor to the beginning of the top line on the current page + FL_Page_Down -- moves the cursor to the beginning of the last line on the current page + \endcode +*/ int Fl_Text_Editor::kf_ctrl_move(int c, Fl_Text_Editor* e) { if (!e->buffer()->selected()) e->dragPos = e->insert_position(); @@ -359,7 +401,15 @@ int Fl_Text_Editor::kf_ctrl_move(int c, Fl_Text_Editor* e) { return 1; } -/** Moves the current text cursor in the direction indicated by meta key */ +/** Moves the current text cursor in the direction indicated by meta key \p 'c' in editor \p 'e'. + Supported values for 'c' are currently: + \code + FL_Up -- moves cursor to the beginning of the current document + FL_Down -- moves cursor to the end of the current document + FL_Left -- moves the cursor to the beginning of the current line + FL_Right -- moves the cursor to the end of the current line + \endcode +*/ int Fl_Text_Editor::kf_meta_move(int c, Fl_Text_Editor* e) { if (!e->buffer()->selected()) e->dragPos = e->insert_position(); @@ -387,65 +437,99 @@ int Fl_Text_Editor::kf_meta_move(int c, Fl_Text_Editor* e) { return 1; } -/** Extends the current selection in the direction indicated by meta key c. */ +/** Extends the current selection in the direction indicated by meta key \p 'c' in editor \p 'e'. + \see kf_meta_move(). +*/ int Fl_Text_Editor::kf_m_s_move(int c, Fl_Text_Editor* e) { kf_meta_move(c, e); fl_text_drag_me(e->insert_position(), e); return 1; } -/** Extends the current selection in the direction indicated by control key c. */ +/** Extends the current selection in the direction indicated by control key \p 'c' in editor \p 'e'. + \see kf_ctrl_move(). +*/ int Fl_Text_Editor::kf_c_s_move(int c, Fl_Text_Editor* e) { kf_ctrl_move(c, e); fl_text_drag_me(e->insert_position(), e); return 1; } -/** Moves the text cursor to the beginning of the current line.*/ +/** Moves the text cursor to the beginning of the current line in editor \p 'e'. + Same as kf_move(FL_Home, e). + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_home(int, Fl_Text_Editor* e) { return kf_move(FL_Home, e); } -/** Moves the text cursor to the end of the current line.*/ +/** Moves the text cursor to the end of the current line in editor \p 'e'. + Same as kf_move(FL_End, e). + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_end(int, Fl_Text_Editor* e) { return kf_move(FL_End, e); } -/** Moves the text cursor one character to the left.*/ +/** Moves the text cursor one character to the left in editor \p 'e'. + Same as kf_move(FL_Left, e). + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_left(int, Fl_Text_Editor* e) { return kf_move(FL_Left, e); } -/** Moves the text cursor one line up.*/ +/** Moves the text cursor one line up for editor \p 'e'. + Same as kf_move(FL_Up, e). + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_up(int, Fl_Text_Editor* e) { return kf_move(FL_Up, e); } -/** Moves the text cursor one character to the right.*/ +/** Moves the text cursor one character to the right for editor \p 'e'. + Same as kf_move(FL_Right, e). + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_right(int, Fl_Text_Editor* e) { return kf_move(FL_Right, e); } -/** Moves the text cursor one line down.*/ + +/** Moves the text cursor one line down for editor \p 'e'. + Same as kf_move(FL_Down, e). + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_down(int, Fl_Text_Editor* e) { return kf_move(FL_Down, e); } -/** Moves the text cursor up one page.*/ +/** Moves the text cursor up one page for editor \p 'e'. + Same as kf_move(FL_Page_Up, e). + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_page_up(int, Fl_Text_Editor* e) { return kf_move(FL_Page_Up, e); } -/** Moves the text cursor down one page.*/ +/** Moves the text cursor down one page for editor \p 'e'. + Same as kf_move(FL_Page_Down, e). + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_page_down(int, Fl_Text_Editor* e) { return kf_move(FL_Page_Down, e); } -/** Toggles the insert mode in the text editor.*/ + +/** Toggles the insert mode for editor \p 'e'. + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_insert(int, Fl_Text_Editor* e) { e->insert_mode(e->insert_mode() ? 0 : 1); return 1; } -/** Does a delete of selected text or the current character in the current buffer.*/ +/** Does a delete of selected text or the current character in the current buffer of editor \p 'e'. + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_delete(int, Fl_Text_Editor* e) { if (!e->buffer()->selected()) { int p1 = e->insert_position(); @@ -460,7 +544,9 @@ int Fl_Text_Editor::kf_delete(int, Fl_Text_Editor* e) { return 1; } -/** Does a copy of selected text or the current character in the current buffer.*/ +/** Does a copy of selected text or the current character in the current buffer of editor \p 'e'. + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_copy(int, Fl_Text_Editor* e) { if (!e->buffer()->selected()) return 1; const char *copy = e->buffer()->selection_text(); @@ -470,7 +556,9 @@ int Fl_Text_Editor::kf_copy(int, Fl_Text_Editor* e) { return 1; } -/** Does a cut of selected text in the current buffer.*/ +/** Does a cut of selected text in the current buffer of editor \p 'e'. + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_cut(int c, Fl_Text_Editor* e) { kf_copy(c, e); kill_selection(e); @@ -479,7 +567,10 @@ int Fl_Text_Editor::kf_cut(int c, Fl_Text_Editor* e) { return 1; } -/** Does a paste of selected text in the current buffer.*/ +/** Does a paste of selected text in the current buffer of editor \p 'e'. + Any current selection is replaced with the pasted content. + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_paste(int, Fl_Text_Editor* e) { kill_selection(e); Fl::paste(*e, 1); @@ -489,7 +580,9 @@ int Fl_Text_Editor::kf_paste(int, Fl_Text_Editor* e) { return 1; } -/** Selects all text in the current buffer.*/ +/** Selects all text in the current buffer in editor \p 'e'. + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_select_all(int, Fl_Text_Editor* e) { e->buffer()->select(0, e->buffer()->length()); const char *copy = e->buffer()->selection_text(); @@ -497,7 +590,11 @@ int Fl_Text_Editor::kf_select_all(int, Fl_Text_Editor* e) { free((void*)copy); return 1; } -/** Undo last edit in the current buffer. Also deselect previous selection. */ + +/** Undo last edit in the current buffer of editor \p 'e'. + Also deselects previous selection. + The key value \p 'c' is currently unused. +*/ int Fl_Text_Editor::kf_undo(int , Fl_Text_Editor* e) { e->buffer()->unselect(); Fl::copy("", 0, 0); -- cgit v1.2.3