mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

added doxygen comments for undocumented methods of Fl_Bitmap and Fl_Browser

Browse Source 
also replaced some html with doxygen equivalent.

note that not all comments are consistent. some are one-liners, even though
the contain [obvious?] parameters, and others have \param and \returns.
note too, that some parameter names are ambiguous and require type info,
eg line could be FL_BLINE* for whole line entry, or int for line number,
and this can make descriptions awkward (\param line line number).



git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6318 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
engelsman 2008-09-20 14:29:29 +00:00
parent 40a156aa94
commit f5a1576d7c
3 changed files with 129 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
FL/Fl_Bitmap.H
View File

@ -42,12 +42,16 @@ struct Fl_Menu_Item;
class FL_EXPORT Fl_Bitmap : public Fl_Image { class FL_EXPORT Fl_Bitmap : public Fl_Image {
public: public:
/** pointer to raw bitmap data */
const uchar *array; const uchar *array;
int alloc_array; // Non-zero if data was allocated /** Non-zero if array points to bitmap data allocated internally */
int alloc_array;
#if defined(__APPLE__) || defined(WIN32) #if defined(__APPLE__) || defined(WIN32)
void *id; // for internal use /** for internal use */
void *id;
#else #else
unsigned id; // for internal use /** for internal use */
unsigned id;
#endif // __APPLE__ || WIN32 #endif // __APPLE__ || WIN32
/** The constructors create a new bitmap from the specified bitmap data */ /** The constructors create a new bitmap from the specified bitmap data */
Fl_Bitmap(const uchar *bits, int W, int H) : Fl_Bitmap(const uchar *bits, int W, int H) :

99
FL/Fl_Browser.H
View File

@ -118,13 +118,10 @@ public:
void size(int W, int H) { Fl_Widget::size(W, H); } void size(int W, int H) { Fl_Widget::size(W, H); }
int topline() const ; int topline() const ;
/** For internal use only? */
enum Fl_Line_Position { TOP, BOTTOM, MIDDLE }; enum Fl_Line_Position { TOP, BOTTOM, MIDDLE };
void lineposition(int, Fl_Line_Position); void lineposition(int, Fl_Line_Position);
/** /** Scrolls the browser so the top line in the browser is n. */
The first form returns the current top line in the browser. If there
is no vertical scrollbar then this will always return 1.
<P>The second form scrolls the browser so the top line in the browser is n.
*/
void topline(int l) { lineposition(l, TOP); } void topline(int l) { lineposition(l, TOP); }
/** Scrolls the browser so the bottom line in the browser is n. */ /** Scrolls the browser so the bottom line in the browser is n. */
void bottomline(int l) { lineposition(l, BOTTOM); } void bottomline(int l) { lineposition(l, BOTTOM); }
@ -140,6 +137,7 @@ public:
int visible(int n) const ; int visible(int n) const ;
int value() const ; int value() const ;
/** Sets the browser's value, i.e. selected line, to \p v */
void value(int v) {select(v);} void value(int v) {select(v);}
const char* text(int) const ; const char* text(int) const ;
void text(int, const char*); void text(int, const char*);
@ -151,79 +149,86 @@ public:
~Fl_Browser() { clear(); } ~Fl_Browser() { clear(); }
/** /**
The first form gets the current format code prefix character, which by Gets the current format code prefix character, which by default is '\@'.
default is '\@'. A string of formatting codes at the start of A string of formatting codes at the start of each column are stripped off
each column are stripped off and used to modify how the rest of the and used to modify how the rest of the line is printed:
line is printed:
<UL> \li <tt>'\@.'</tt> Print rest of line, don't look for more '\@' signs
<LI><tt>'\@.'</tt> Print rest of line, don't look for more '\@' signs </LI> \li <tt>'\@\@'</tt> Print rest of line starting with '\@'
<LI><tt>'\@\@'</tt> Print rest of line starting with '\@' </LI> \li <tt>'\@l'</tt> Use a LARGE (24 point) font
<LI><tt>'\@l'</tt> Use a LARGE (24 point) font </LI> \li <tt>'\@m'</tt> Use a medium large (18 point) font
<LI><tt>'\@m'</tt> Use a medium large (18 point) font </LI> \li <tt>'\@s'</tt> Use a <SMALL>small</SMALL> (11 point) font
<LI><tt>'\@s'</tt> Use a <SMALL>small</SMALL> (11 point) font </LI> \li <tt>'\@b'</tt> Use a <B>bold</B> font (adds FL_BOLD to font)
<LI><tt>'\@b'</tt> Use a <B>bold</B> font (adds FL_BOLD to font) </LI> \li <tt>'\@i'</tt> Use an <I>italic</I> font (adds FL_ITALIC to font)
<LI><tt>'\@i'</tt> Use an <I>italic</I> font (adds FL_ITALIC to font) </LI> \li <tt>'\@f' or '\@t'</tt> Use a fixed-pitch
<LI><tt>'\@f' or '\@t'</tt> Use a fixed-pitch font (sets font to FL_COURIER)
font (sets font to FL_COURIER) </LI> \li <tt>'\@c'</tt> Center the line horizontally
<LI><tt>'\@c'</tt> Center the line horizontally </LI> \li <tt>'\@r'</tt> Right-justify the text
<LI><tt>'\@r'</tt> Right-justify the text </LI> \li <tt>'\@B0', '\@B1', ... '\@B255'</tt> Fill the backgound with
<LI><tt>'\@B0', '\@B1', ... '\@B255'</tt> Fill the backgound with fl_color(n)
fl_color(n) </LI> \li <tt>'\@C0', '\@C1', ... '\@C255'</tt> Use fl_color(n) to draw the text
<LI><tt>'\@C0', '\@C1', ... '\@C255'</tt> Use fl_color(n) to draw the text </LI> \li <tt>'\@F0', '\@F1', ...</tt> Use fl_font(n) to draw the text
<LI><tt>'\@F0', '\@F1', ...</tt> Use fl_font(n) to draw the text </LI> \li <tt>'\@S1', '\@S2', ...</tt> Use point size n to draw the text
<LI><tt>'\@S1', '\@S2', ...</tt> Use point size n to draw the text </LI> \li <tt>'\@u' or '\@_'</tt> Underline the text.
<LI><tt>'\@u' or '\@_'</tt> Underline the text. </LI> \li <tt>'\@-'</tt> draw an engraved line through the middle.
<LI><tt>'\@-'</tt> draw an engraved line through the middle. </LI>
</UL>
Notice that the '\@.' command can be used to reliably Notice that the '\@.' command can be used to reliably
terminate the parsing. To print a random string in a random color, use terminate the parsing. To print a random string in a random color, use
<tt>sprintf("\@C%d\@.%s", color, string)</tt> and it will work even if the <tt>sprintf("\@C%d\@.%s", color, string)</tt> and it will work even if the
string starts with a digit or has the format character in it. string starts with a digit or has the format character in it.
<P>The second form sets the current prefix to c. Set the
prefix to 0 to disable formatting.
*/ */
char format_char() const {return format_char_;} char format_char() const {return format_char_;}
/** See uchar Fl_Browser::format_char() const */ /**
Sets the current format code prefix character to \p c.
The default prefix is '\@'. Set the prefix to 0 to disable formatting.
\see uchar Fl_Browser::format_char() const
*/
void format_char(char c) {format_char_ = c;} void format_char(char c) {format_char_ = c;}
/** /**
The first form gets the current column separator character. By default Gets the current column separator character.
this is '\\t' (tab). By default this is '\\t' (tab).
<P>The second form sets the column separator to c. This will
only have an effect if you also set column_widths().
*/ */
char column_char() const {return column_char_;} char column_char() const {return column_char_;}
/** /**
The first form gets the current column separator character. By default Sets the column separator to c.
this is '\\t' (tab). This will only have an effect if you also set column_widths().
<P>The second form sets the column separator to c. This will
only have an effect if you also set column_widths().
*/ */
void column_char(char c) {column_char_ = c;} void column_char(char c) {column_char_ = c;}
/** /**
The first form gets the current column width array. This array is Gets the current column width array. This array is
zero-terminated and specifies the widths in pixels of each column. The zero-terminated and specifies the widths in pixels of each column. The
text is split at each column_char() and each part is formatted text is split at each column_char() and each part is formatted
into it's own column. After the last column any remaining text is into it's own column. After the last column any remaining text is
formatted into the space between the last column and the right edge of formatted into the space between the last column and the right edge of
the browser, even if the text contains instances of column_char() the browser, even if the text contains instances of column_char() .
. The default value is a one-element array of just a zero, which makes The default value is a one-element array of just a zero, which means
there are no columns. there are no columns.
<P>The second form sets the current array to w. Make sure the
last entry is zero.
*/ */
const int* column_widths() const {return column_widths_;} const int* column_widths() const {return column_widths_;}
/** See const int *Fl_Browser::column_widths() const */ /**
Sets the current array to w. Make sure the last entry is zero.
\see const int *Fl_Browser::column_widths() const
*/
void column_widths(const int* l) {column_widths_ = l;} void column_widths(const int* l) {column_widths_ = l;}
/**
Returns non-zero if line \p n is visible.
*/
int displayed(int n) const {return Fl_Browser_::displayed(find_line(n));} int displayed(int n) const {return Fl_Browser_::displayed(find_line(n));}
/**
Redisplays so that line \p n is visible.
If \p n is out of range, redisplay top or botton of list as appropriate.
*/
void make_visible(int n) { void make_visible(int n) {
if (n < 1) Fl_Browser_::display(find_line(1)); if (n < 1) Fl_Browser_::display(find_line(1));
else if (n > lines) Fl_Browser_::display(find_line(lines)); else if (n > lines) Fl_Browser_::display(find_line(lines));
else Fl_Browser_::display(find_line(n)); else Fl_Browser_::display(find_line(n));
} }
// for back compatibility only: /** For back compatibility only. */
void replace(int a, const char* b) {text(a, b);} void replace(int a, const char* b) {text(a, b);}
void display(int, int=1); void display(int, int=1);
}; };

96
src/Fl_Browser.cxx
View File

@ -68,6 +68,9 @@ void Fl_Browser::item_select(void* l, int v) {
else ((FL_BLINE*)l)->flags &= ~SELECTED; else ((FL_BLINE*)l)->flags &= ~SELECTED;
} }
/**
Return entry for line number \p line.
*/
FL_BLINE* Fl_Browser::find_line(int line) const { FL_BLINE* Fl_Browser::find_line(int line) const {
int n; FL_BLINE* l; int n; FL_BLINE* l;
if (line == cacheline) return cache; if (line == cacheline) return cache;
@ -85,6 +88,10 @@ FL_BLINE* Fl_Browser::find_line(int line) const {
return l; return l;
} }
/**
Returns line number corresponding to data \p v,
zero if not found.
*/
int Fl_Browser::lineno(void* v) const { int Fl_Browser::lineno(void* v) const {
FL_BLINE* l = (FL_BLINE*)v; FL_BLINE* l = (FL_BLINE*)v;
if (!l) return 0; if (!l) return 0;
@ -112,6 +119,11 @@ int Fl_Browser::lineno(void* v) const {
return n; return n;
} }
/**
Remove entry for given line number.
\param[in] line line number. Must be in range!
\returns pointer to browser entry.
*/
FL_BLINE* Fl_Browser::_remove(int line) { FL_BLINE* Fl_Browser::_remove(int line) {
FL_BLINE* ttt = find_line(line); FL_BLINE* ttt = find_line(line);
deleting(ttt); deleting(ttt);
@ -128,14 +140,16 @@ FL_BLINE* Fl_Browser::_remove(int line) {
return(ttt); return(ttt);
} }
/** Remove line n and make the browser one line shorter.*/ /**
Remove line n and make the browser one line shorter.
*/
void Fl_Browser::remove(int line) { void Fl_Browser::remove(int line) {
if (line < 1 || line > lines) return; if (line < 1 || line > lines) return;
free(_remove(line)); free(_remove(line));
} }
/** /**
Insert a new line <I>before</I> line n. If n &gt; Insert a new line \p t \e before line \p n. If \p n &gt;
size() then the line is added to the end. size() then the line is added to the end.
*/ */
void Fl_Browser::insert(int line, FL_BLINE* t) { void Fl_Browser::insert(int line, FL_BLINE* t) {
@ -168,6 +182,12 @@ void Fl_Browser::insert(int line, FL_BLINE* t) {
redraw_line(t); redraw_line(t);
} }
/**
Insert a new entry \e before given line.
\param[in] line if \p line > size(), the entry will be added at the end.
\param[in] newtext text entry for the new line.
\param[in] d pointer to data associated with the new line.
*/
void Fl_Browser::insert(int line, const char* newtext, void* d) { void Fl_Browser::insert(int line, const char* newtext, void* d) {
int l = strlen(newtext); int l = strlen(newtext);
FL_BLINE* t = (FL_BLINE*)malloc(sizeof(FL_BLINE)+l); FL_BLINE* t = (FL_BLINE*)malloc(sizeof(FL_BLINE)+l);
@ -188,14 +208,8 @@ void Fl_Browser::move(int to, int from) {
} }
/** /**
The first form returns the text for line n. If n is Sets the text for line \p line to text \p newtext.
out of range it returns NULL. Does nothing if \p line is out of range.
<P>The second form sets the text for line n.
*/
/**
The first form returns the text for line n. If n is
out of range it returns NULL.
<P>The second form sets the text for line n.
*/ */
void Fl_Browser::text(int line, const char* newtext) { void Fl_Browser::text(int line, const char* newtext) {
if (line < 1 || line > lines) return; if (line < 1 || line > lines) return;
@ -220,20 +234,17 @@ void Fl_Browser::text(int line, const char* newtext) {
} }
/** /**
The first form returns the data for line n. If n is Sets the data for line \p n to \p d.
out of range this returns NULL. Does nothing if \n is out of range.
<P>The second form sets the data for line n.
*/
/**
The first form returns the data for line n. If n is
out of range this returns NULL.
<P>The second form sets the data for line n.
*/ */
void Fl_Browser::data(int line, void* d) { void Fl_Browser::data(int line, void* d) {
if (line < 1 || line > lines) return; if (line < 1 || line > lines) return;
find_line(line)->data = d; find_line(line)->data = d;
} }
/**
Returns height of line \p lv.
*/
int Fl_Browser::item_height(void* lv) const { int Fl_Browser::item_height(void* lv) const {
FL_BLINE* l = (FL_BLINE*)lv; FL_BLINE* l = (FL_BLINE*)lv;
if (l->flags & NOTDISPLAYED) return 0; if (l->flags & NOTDISPLAYED) return 0;
@ -421,9 +432,13 @@ void Fl_Browser::item_draw(void* v, int X, int Y, int W, int H) const {
static const int no_columns[1] = {0}; static const int no_columns[1] = {0};
/** The constructor makes an empty browser.*/ /**
Fl_Browser::Fl_Browser(int X, int Y, int W, int H, const char*l) The constructor makes an empty browser.
: Fl_Browser_(X, Y, W, H, l) { \param[in] X,Y,W,H position and size.
\param[in] L label string, may be NULL.
*/
Fl_Browser::Fl_Browser(int X, int Y, int W, int H, const char*L)
: Fl_Browser_(X, Y, W, H, L) {
column_widths_ = no_columns; column_widths_ = no_columns;
lines = 0; lines = 0;
full_height_ = 0; full_height_ = 0;
@ -433,6 +448,11 @@ Fl_Browser::Fl_Browser(int X, int Y, int W, int H, const char*l)
first = last = cache = 0; first = last = cache = 0;
} }
/**
Update browser so that line is shown at given position.
\param[in] line line number.
\param[in] pos position.
*/
void Fl_Browser::lineposition(int line, Fl_Line_Position pos) { void Fl_Browser::lineposition(int line, Fl_Line_Position pos) {
if (line<1) line = 1; if (line<1) line = 1;
if (line>lines) line = lines; if (line>lines) line = lines;
@ -458,15 +478,16 @@ void Fl_Browser::lineposition(int line, Fl_Line_Position pos) {
} }
/** /**
The first form returns the current top line in the browser. If there Returns the current top line in the browser. If there
is no vertical scrollbar then this will always return 1. is no vertical scrollbar then this will always return 1.
<P>The second form scrolls the browser so the top line in the browser is n.
*/ */
int Fl_Browser::topline() const { int Fl_Browser::topline() const {
return lineno(top()); return lineno(top());
} }
/** Remove all the lines in the browser.*/ /**
Remove all the lines in the browser.
*/
void Fl_Browser::clear() { void Fl_Browser::clear() {
for (FL_BLINE* l = first; l;) { for (FL_BLINE* l = first; l;) {
FL_BLINE* n = l->next; FL_BLINE* n = l->next;
@ -490,16 +511,28 @@ void Fl_Browser::add(const char* newtext, void* d) {
//Fl_Browser_::display(last); //Fl_Browser_::display(last);
} }
/**
Returns data entry for line \p line, or NULL if out of range.
*/
const char* Fl_Browser::text(int line) const { const char* Fl_Browser::text(int line) const {
if (line < 1 || line > lines) return 0; if (line < 1 || line > lines) return 0;
return find_line(line)->txt; return find_line(line)->txt;
} }
/**
Returns the data for line \p n, or NULL is \p n is out of range.
*/
void* Fl_Browser::data(int line) const { void* Fl_Browser::data(int line) const {
if (line < 1 || line > lines) return 0; if (line < 1 || line > lines) return 0;
return find_line(line)->data; return find_line(line)->data;
} }
/**
Sets the selection state of entry.
\param[in] line line number.
\param[in] v new selection state.
\returns 1 if the state changed, 0 if not.
*/
int Fl_Browser::select(int line, int v) { int Fl_Browser::select(int line, int v) {
if (line < 1 || line > lines) return 0; if (line < 1 || line > lines) return 0;
return Fl_Browser_::select(find_line(line), v); return Fl_Browser_::select(find_line(line), v);
@ -534,22 +567,33 @@ void Fl_Browser::hide(int line) {
} }
} }
/**
For back compatibility.
*/
void Fl_Browser::display(int line, int v) { void Fl_Browser::display(int line, int v) {
if (line < 1 || line > lines) return; if (line < 1 || line > lines) return;
if (v) show(line); else hide(line); if (v) show(line); else hide(line);
} }
/** Returns a non-zero value if line n is visible.*/ /**
Returns a non-zero value if line is visible.
*/
int Fl_Browser::visible(int line) const { int Fl_Browser::visible(int line) const {
if (line < 1 || line > lines) return 0; if (line < 1 || line > lines) return 0;
return !(find_line(line)->flags&NOTDISPLAYED); return !(find_line(line)->flags&NOTDISPLAYED);
} }
/**
Gets browser value.
\returns line number of current selection, or 0 if no selection.
*/
int Fl_Browser::value() const { int Fl_Browser::value() const {
return lineno(selection()); return lineno(selection());
} }
// SWAP TWO LINES /**
Swap two lines, \p a and \p b
*/
void Fl_Browser::swap(FL_BLINE *a, FL_BLINE *b) { void Fl_Browser::swap(FL_BLINE *a, FL_BLINE *b) {
if ( a == b || !a || !b) return; // nothing to do if ( a == b || !a || !b) return; // nothing to do