Doxygen documentation WP11 Done!

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6255 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

1 files changed, 51 insertions, 1 deletions

diff --git a/FL/Fl_Text_Buffer.H b/FL/Fl_Text_Buffer.H
index aa4bbf704..5f8e4bd75 100644
--- a/FL/Fl_Text_Buffer.H
+++ b/FL/Fl_Text_Buffer.H
@@ -48,6 +48,10 @@ class FL_EXPORT Fl_Text_Selection {
     int end() { return mEnd; }
     int rect_start() { return mRectStart; }
     int rect_end() { return mRectEnd; }
+    /**
+       Returns a non-zero number if any text has been selected, or 0
+       if no text is selected.
+    */
     char selected() { return mSelected; }
     void selected(char b) { mSelected = b; }
     int includes(int pos, int lineStartPos, int dispIndex);
@@ -69,11 +73,26 @@ typedef void (*Fl_Text_Modify_Cb)(int pos, int nInserted, int nDeleted,
                                   void* cbArg);
 typedef void (*Fl_Text_Predelete_Cb)(int pos, int nDeleted, void* cbArg);
 
+/**
+  The Fl_Text_Buffer class is used by the Fl_Text_Display
+  and Fl_Text_Editor to manage complex text data and is based upon the
+  excellent NEdit text editor engine - see http://www.nedit.org/.
+*/
+/**
+  The Fl_Text_Buffer class is used by the 
+  Fl_Text_Display
+  and 
+  Fl_Text_Editor
+  to manage complex text data and is based upon the
+  excellent NEdit text editor engine - see
+  http://www.nedit.org/.
+*/
 class FL_EXPORT Fl_Text_Buffer {
   public:
     Fl_Text_Buffer(int requestedSize = 0);
     ~Fl_Text_Buffer();
 
+  /**    Returns the number of characters in the buffer.  */
     int length() { return mLength; }
     char* text();
     void text(const char* text);
@@ -81,6 +100,7 @@ class FL_EXPORT Fl_Text_Buffer {
     char character(int pos);
     char* text_in_rectangle(int start, int end, int rectStart, int rectEnd);
     void insert(int pos, const char* text);
+  /**    Appends the text string to the end of the buffer.  */
     void append(const char* t) { insert(length(), t); }
     void remove(int start, int end);
     void replace(int start, int end, const char *text);
@@ -88,11 +108,19 @@ class FL_EXPORT Fl_Text_Buffer {
     int undo(int *cp=0);
     void canUndo(char flag=1);
     int insertfile(const char *file, int pos, int buflen = 128*1024);
+    /**
+      Appends the named file to the end of the buffer. Returns 0 on 
+      success, non-zero on error (strerror() contains reason).  1 indicates 
+      open for read failed (no data loaded). 2 indicates error occurred 
+      while reading data (data was partially loaded).
+    */
     int appendfile(const char *file, int buflen = 128*1024)
       { return insertfile(file, length(), buflen); }
+    /** Loads a text file into the buffer */
     int loadfile(const char *file, int buflen = 128*1024)
       { select(0, length()); remove_selection(); return appendfile(file, buflen); }
     int outputfile(const char *file, int start, int end, int buflen = 128*1024);
+    /** Saves a text file from the current buffer */
     int savefile(const char *file, int buflen = 128*1024)
       { return outputfile(file, 0, length(), buflen); }
 
@@ -108,9 +136,11 @@ class FL_EXPORT Fl_Text_Buffer {
 
     void remove_rectangular(int start, int end, int rectStart, int rectEnd);
     void clear_rectangular(int start, int end, int rectStart, int rectEnd);
+    /** Gets the tab width.  */
     int tab_distance() { return mTabDist; }
     void tab_distance(int tabDist);
     void select(int start, int end);
+    /** Returns a non 0 value if text has been selected, 0 otherwise */
     int selected() { return mPrimary.selected(); }
     void unselect();
     void select_rectangular(int start, int end, int rectStart, int rectEnd);
@@ -123,7 +153,10 @@ class FL_EXPORT Fl_Text_Buffer {
     void remove_selection();
     void replace_selection(const char* text);
     void secondary_select(int start, int end);
+     /** Returns a non 0 value if text has been selected in the secondary
+       text selection, 0 otherwise */
     int secondary_selected() { return mSecondary.selected(); }
+     /** Clears any selection in the secondary text selection object. */
     void secondary_unselect();
 
     void secondary_select_rectangular(int start, int end, int rectStart,
@@ -137,6 +170,10 @@ class FL_EXPORT Fl_Text_Buffer {
     void remove_secondary_selection();
     void replace_secondary_selection(const char* text);
     void highlight(int start, int end);
+    /**
+      Returns the highlighted text. When you are done with the
+      text, free it using the free() function.
+    */
     int highlight() { return mHighlight.selected(); }
     void unhighlight();
     void highlight_rectangular(int start, int end, int rectStart, int rectEnd);
@@ -149,12 +186,21 @@ class FL_EXPORT Fl_Text_Buffer {
     void add_modify_callback(Fl_Text_Modify_Cb bufModifiedCB, void* cbArg);
     void remove_modify_callback(Fl_Text_Modify_Cb bufModifiedCB, void* cbArg);
 
+    /**
+       Calls all modify callbacks that have been registered using
+       the add_modify_callback()
+       method.
+    */
     void call_modify_callbacks() { call_modify_callbacks(0, 0, 0, 0, 0); }
 
     void add_predelete_callback(Fl_Text_Predelete_Cb bufPredelCB, void* cbArg);
     void remove_predelete_callback(Fl_Text_Predelete_Cb predelCB, void* cbArg);
 
-    void call_predelete_callbacks() { call_predelete_callbacks(0, 0); }
+   /**
+     Calls the stored pre-delete callback procedure(s) for this buffer to update 
+     the changed area(s) on the screen and any other listeners.
+   */
+   void call_predelete_callbacks() { call_predelete_callbacks(0, 0); }
 
     char* line_text(int pos);
     int line_start(int pos);
@@ -185,9 +231,13 @@ class FL_EXPORT Fl_Text_Buffer {
 
     int substitute_null_characters(char* string, int length);
     void unsubstitute_null_characters(char* string);
+    /**    Returns the current nul substitution character.  */
     char null_substitution_character() { return mNullSubsChar; }
+    /**    Returns the primary selection.  */
     Fl_Text_Selection* primary_selection() { return &mPrimary; }
+    /**    Returns the secondary selection.  */
     Fl_Text_Selection* secondary_selection() { return &mSecondary; }
+    /**    Returns the current highlight selection.  */
     Fl_Text_Selection* highlight_selection() { return &mHighlight; }
 
   protected: