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 {
public:
/** pointer to raw bitmap data */
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)
void *id; // for internal use
/** for internal use */
void *id;
#else
unsigned id; // for internal use
/** for internal use */
unsigned id;
#endif // __APPLE__ || WIN32
/** The constructors create a new bitmap from the specified bitmap data */
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); }
int topline() const ;
/** For internal use only? */
enum Fl_Line_Position { TOP, BOTTOM, MIDDLE };
void lineposition(int, Fl_Line_Position);
/**
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.
*/
/** Scrolls the browser so the top line in the browser is n. */
void topline(int l) { lineposition(l, TOP); }
/** Scrolls the browser so the bottom line in the browser is n. */
void bottomline(int l) { lineposition(l, BOTTOM); }
@ -140,6 +137,7 @@ public:
int visible(int n) const ;
int value() const ;
/** Sets the browser's value, i.e. selected line, to \p v */
void value(int v) {select(v);}
const char* text(int) const ;
void text(int, const char*);
@ -151,79 +149,86 @@ public:
~Fl_Browser() { clear(); }
/**
The first form gets the current format code prefix character, which by
default is '\@'. A string of formatting codes at the start of
each column are stripped off and used to modify how the rest of the
line is printed:
<UL>
<LI><tt>'\@.'</tt> Print rest of line, don't look for more '\@' signs </LI>
<LI><tt>'\@\@'</tt> Print rest of line starting with '\@' </LI>
<LI><tt>'\@l'</tt> Use a LARGE (24 point) font </LI>
<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>
<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>
<LI><tt>'\@f' or '\@t'</tt> Use a fixed-pitch
font (sets font to FL_COURIER) </LI>
<LI><tt>'\@c'</tt> Center the line horizontally </LI>
<LI><tt>'\@r'</tt> Right-justify the text </LI>
<LI><tt>'\@B0', '\@B1', ... '\@B255'</tt> Fill the backgound with
fl_color(n) </LI>
<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>
<LI><tt>'\@S1', '\@S2', ...</tt> Use point size n to draw the text </LI>
<LI><tt>'\@u' or '\@_'</tt> Underline the text. </LI>
<LI><tt>'\@-'</tt> draw an engraved line through the middle. </LI>
</UL>
Gets the current format code prefix character, which by default is '\@'.
A string of formatting codes at the start of each column are stripped off
and used to modify how the rest of the line is printed:
\li <tt>'\@.'</tt> Print rest of line, don't look for more '\@' signs
\li <tt>'\@\@'</tt> Print rest of line starting with '\@'
\li <tt>'\@l'</tt> Use a LARGE (24 point) font
\li <tt>'\@m'</tt> Use a medium large (18 point) font
\li <tt>'\@s'</tt> Use a <SMALL>small</SMALL> (11 point) font
\li <tt>'\@b'</tt> Use a <B>bold</B> font (adds FL_BOLD to font)
\li <tt>'\@i'</tt> Use an <I>italic</I> font (adds FL_ITALIC to font)
\li <tt>'\@f' or '\@t'</tt> Use a fixed-pitch
font (sets font to FL_COURIER)
\li <tt>'\@c'</tt> Center the line horizontally
\li <tt>'\@r'</tt> Right-justify the text
\li <tt>'\@B0', '\@B1', ... '\@B255'</tt> Fill the backgound with
fl_color(n)
\li <tt>'\@C0', '\@C1', ... '\@C255'</tt> Use fl_color(n) to draw the text
\li <tt>'\@F0', '\@F1', ...</tt> Use fl_font(n) to draw the text
\li <tt>'\@S1', '\@S2', ...</tt> Use point size n to draw the text
\li <tt>'\@u' or '\@_'</tt> Underline the text.
\li <tt>'\@-'</tt> draw an engraved line through the middle.
Notice that the '\@.' command can be used to reliably
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
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_;}
/** 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;}
/**
The first form gets the current column separator character. 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().
Gets the current column separator character.
By default this is '\\t' (tab).
*/
char column_char() const {return column_char_;}
/**
The first form gets the current column separator character. 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().
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;}
/**
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
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
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 default value is a one-element array of just a zero, which makes
the browser, even if the text contains instances of column_char() .
The default value is a one-element array of just a zero, which means
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_;}
/** 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;}
/**
Returns non-zero if line \p n is visible.
*/
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) {
if (n < 1) Fl_Browser_::display(find_line(1));
else if (n > lines) Fl_Browser_::display(find_line(lines));
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 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;
}
/**
Return entry for line number \p line.
*/
FL_BLINE* Fl_Browser::find_line(int line) const {
int n; FL_BLINE* l;
if (line == cacheline) return cache;
@ -85,6 +88,10 @@ FL_BLINE* Fl_Browser::find_line(int line) const {
return l;
}
/**
Returns line number corresponding to data \p v,
zero if not found.
*/
int Fl_Browser::lineno(void* v) const {
FL_BLINE* l = (FL_BLINE*)v;
if (!l) return 0;
@ -112,6 +119,11 @@ int Fl_Browser::lineno(void* v) const {
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* ttt = find_line(line);
deleting(ttt);
@ -128,14 +140,16 @@ FL_BLINE* Fl_Browser::_remove(int line) {
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) {
if (line < 1 || line > lines) return;
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.
*/
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);
}
/**
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) {
int l = strlen(newtext);
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
out of range it returns NULL.
<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.
Sets the text for line \p line to text \p newtext.
Does nothing if \p line is out of range.
*/
void Fl_Browser::text(int line, const char* newtext) {
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
out of range this returns NULL.
<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.
Sets the data for line \p n to \p d.
Does nothing if \n is out of range.
*/
void Fl_Browser::data(int line, void* d) {
if (line < 1 || line > lines) return;
find_line(line)->data = d;
}
/**
Returns height of line \p lv.
*/
int Fl_Browser::item_height(void* lv) const {
FL_BLINE* l = (FL_BLINE*)lv;
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};
/** The constructor makes an empty browser.*/
Fl_Browser::Fl_Browser(int X, int Y, int W, int H, const char*l)
: Fl_Browser_(X, Y, W, H, l) {
/**
The constructor makes an empty browser.
\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;
lines = 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;
}
/**
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) {
if (line<1) line = 1;
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.
<P>The second form scrolls the browser so the top line in the browser is n.
*/
int Fl_Browser::topline() const {
return lineno(top());
}
/** Remove all the lines in the browser.*/
/**
Remove all the lines in the browser.
*/
void Fl_Browser::clear() {
for (FL_BLINE* l = first; l;) {
FL_BLINE* n = l->next;
@ -490,16 +511,28 @@ void Fl_Browser::add(const char* newtext, void* d) {
//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 {
if (line < 1 || line > lines) return 0;
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 {
if (line < 1 || line > lines) return 0;
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) {
if (line < 1 || line > lines) return 0;
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) {
if (line < 1 || line > lines) return;
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 {
if (line < 1 || line > lines) return 0;
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 {
return lineno(selection());
}
// SWAP TWO LINES
/**
Swap two lines, \p a and \p b
*/
void Fl_Browser::swap(FL_BLINE *a, FL_BLINE *b) {
if ( a == b || !a || !b) return; // nothing to do