diff options
118 files changed, 13789 insertions, 0 deletions
diff --git a/documentation/FL.gif b/documentation/FL.gif Binary files differnew file mode 100644 index 000000000..7e542b8ae --- /dev/null +++ b/documentation/FL.gif diff --git a/documentation/Fl_Adjuster.html b/documentation/Fl_Adjuster.html new file mode 100644 index 000000000..d7cdf0a90 --- /dev/null +++ b/documentation/Fl_Adjuster.html @@ -0,0 +1,61 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Adjuster">class Fl_Adjuster</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Valuator">Fl_Valuator</a> + | + +----<b>Fl_Adjuster</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Adjuster.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Adjuster</tt> widget was stolen from Prisms, and has +proven to be very useful for values that need a large dynamic range. +When you press a button and drag to the right the value increases. When +you drag to the left it decreases. The largest button adjusts by +<tt>100 * step()</tt>, the next by <tt>10 * step()</tt> and that +smallest button by <tt>step()</tt>. Clicking on the buttons increments +by 10 times the amount dragging by a pixel does. Shift + click +decrements by 10 times the amount. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Adjuster.Fl_Adjuster">Fl_Adjuster</a> + <li><a href="#Fl_Adjuster.~Fl_Adjuster">~Fl_Adjuster</a> + <li><a href="#Fl_Adjuster.soft">soft</a> +</ul> + +<h4><a name="Fl_Adjuster.Fl_Adjuster">Fl_Adjuster::Fl_Adjuster(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Adjuster</tt> widget using the given position, size, and +label string. It looks best if one of the dimensions is 3 times the other. + +<h4><a name="Fl_Adjuster.~Fl_Adjuster">virtual Fl_Adjuster::~Fl_Adjuster()</a></h4> + +Destroys the valuator. + +<h4><a name="Fl_Adjuster.soft">uchar Fl_Adjuster::soft() const<br> +void Fl_Adjuster::soft(uchar)</a></h4> + +If "soft" is turned on, the user is allowed to drag the value outside +the range. If they drag the value to one of the ends, let go, then +grab again and continue to drag, they can get to any value. Default +is one. + +</body> +</html> diff --git a/documentation/Fl_Box.html b/documentation/Fl_Box.html new file mode 100644 index 000000000..e702d863d --- /dev/null +++ b/documentation/Fl_Box.html @@ -0,0 +1,52 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Box">class Fl_Box</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Box</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Box.H> +</pre></ul> + +<h3>Description</h3> + +This widget simply draws its box, and possibly it's label. Putting it +before some other widgets and making it big enough to surround them +will let you draw a frame around them. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Box.Fl_Box">Fl_Box</a> + <li><a href="#Fl_Box.~Fl_Box">~Fl_Box</a> +</ul> + +<h4><a name="Fl_Box.Fl_Box">Fl_Box::Fl_Box(int x, int y, int w, int h, const char * = 0)<br> +Fl_Box::Fl_Box(Fl_Boxtype b, int x, int y, int w, int h, const char *)</a></h4> + +The first constructor sets <tt>box()</tt> to <tt>FL_NO_BOX</tt>, which +means it is invisible. However such widgets are useful as placeholders +or <a href=#Fl_Group.resizable"><tt>Fl_Group::resizable()</tt></a> +values. To change the box to something visible, use <tt>box(n)</tt>. + +<p>The second form of the constructor sets the box to the specified box type. + +<h4><a name="Fl_Box.~Fl_Box">Fl_Box::~Fl_Box(void)</a></h4> + +The destructor removes the box. + +</body> +</html> diff --git a/documentation/Fl_Browser.html b/documentation/Fl_Browser.html new file mode 100644 index 000000000..c0219955c --- /dev/null +++ b/documentation/Fl_Browser.html @@ -0,0 +1,276 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Browser">class Fl_Browser</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Browser_">Fl_Browser_</a> + | + +----<b>Fl_Browser</b> + | + +----<a href="#Fl_Hold_Browser">Fl_Hold_Browser</a>, <a href="#Fl_Multi_Browser">Fl_Multi_Browser</a>, <a href="#Fl_Select_Browser">Fl_Select_Browser</a> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Browser.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Browser</tt> widget displays a scrolling list of text lines, +and manages all the storage for the text. This is not a text editor or +spreadsheet! But it is useful for showing a vertical list of named +objects to the user. + +<p>Each line in the browser is identified by number. <i>The numbers +start at one</i> (this is so that zero can be reserved for "no line" +in the selective browsers). <i>Unless otherwise noted, the methods do +not check to see if the passed line number is in range and legal. It +must always be greater than zero and <= <tt>size()</tt>.</i> + +<p>Each line contains a null-terminated string of text and a <tt>void +*</tt> data pointer. The text string is displayed, the <tt>void *</tt> +pointer can be used by the callbacks to reference the object the text +describes. + +<p>The base class does nothing when the user clicks on it. The subclasses +<a href="#Fl_Select_Browser"><tt>Fl_Select_Browser</tt></a>, +<a href="#Fl_Hold_Browser"><tt>Fl_Hold_Browser</tt></a>, and +<a href="#Fl_Multi_Browser"><tt>Fl_Multi_Browser</tt></a> +react to user clicks to select lines in the browser and do callbacks. + +<p>The base class called <a href="#Fl_Browser_"> +<tt>Fl_Browser_</tt></a> provides the scrolling and selection +mechanisms of this and all the subclasses, but the dimensions and +appearance of each item are determined by the subclass. You can use +<tt>Fl_Browser_</tt> to display information other than text, or text +that is dynamically produced from your own data structures. If you find +that loading the browser is a lot of work or is inefficient, you may +want to make a subclass of <tt>Fl_Browser_</tt>. + +<h3>Methods</h3> + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Browser.Fl_Browser">Fl_Browser</a> + <li><a href="#Fl_Browser.~Fl_Browser">~Fl_Browser</a> + <li><a href="#Fl_Browser.add">add</a> + <li><a href="#Fl_Browser.clear">clear</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Browser.column_char">column_char</a> + <li><a href="#Fl_Browser.column_widths">column_widths</a> + <li><a href="#Fl_Browser.data">data</a> + <li><a href="#Fl_Browser.format_char">format_char</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Browser.hide">hide</a> + <li><a href="#Fl_Browser.insert">insert</a> + <li><a href="#Fl_Browser.load">load</a> + <li><a href="#Fl_Browser.move">move</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Browser.position">position</a> + <li><a href="#Fl_Browser.remove">remove</a> + <li><a href="#Fl_Browser.show">show</a> + <li><a href="#Fl_Browser.size">size</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Browser.text">text</a> + <li><a href="#Fl_Browser.topline">topline</a> + <li><a href="#Fl_Browser.visible">visible</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4><a name="Fl_Browser.Fl_Browser">Fl_Browser::Fl_Browser(int, int, int, int, const char * = 0)</a></h4> + +The constructor makes an empty browser. + +<h4><a name="Fl_Browser.~Fl_Browser">Fl_Browser::~Fl_Browser(void)</a></h4> + +The destructor deletes all list items and destroys the browser. + +<h4><a name="Fl_Browser.add">void Fl_Browser::add(const char *, void * = 0)</a></h4> + +Add a new line to the end of the browser. The text is copied using the +<tt>strdup()</tt> function. It may also be <tt>NULL</tt> to make a +blank line. The <tt>void *</tt> argument is returned as the +<tt>data()</tt> of the new item. + +<h4><a name="Fl_Browser.clear">void Fl_Browser::clear()</a></h4> + +Remove all the lines in the browser. + +<h4><a name="Fl_Browser.column_char">uchar Fl_Browser::column_char() const<br> +void Fl_Browser::column_char(char c)</a></h4> + +The first form gets the current column separator character. By default this is +<tt>'\t'</tt> (tab). + +<p>The second form sets the column separator to <tt>c</tt>. This will only +have an effect if you also set <tt>column_widths()</tt>. + +<h4><a name="Fl_Browser.column_widths">const int *Fl_Browser::column_widths() const<br> +void Fl_Browser::column_widths(const int *w)</a></h4> + +The first form 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 <tt>column_char()</tt> 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 +<tt>column_char()</tt>. The default value is a one-element array of +just a zero, which makes there are no columns. + +<p>The second form sets the current array to <tt>w</tt>. Make sure the last +entry is zero. + +<h4><a name="Fl_Browser.data">void *Fl_Browser::data(int n) const<br> +void Fl_Browser::data(int n, void *)</a></h4> + +The first form returns the data for line <tt>n</tt>. If <tt>n</tt> is +out of range this returns <tt>NULL</tt>. + +<p>The second form sets the data for line <tt>n</tt>. + +<h4><a name="Fl_Browser.format_char">uchar Fl_Browser::format_char() const<br> +void Fl_Browser::format_char(char c)</a></h4> + +The first form gets the current format code prefix character, which by +default is <tt>@</tt>. 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><code>@.</code> Print rest of line, don't look for more '@' signs + + <li><code>@@</code> Print rest of line starting with '@' + + <li><code>@l</code> Use a <big>large</big> (24 point) font + + <li><code>@m</code> Use a <big>medium large</big> (18 point) font + + <li><code>@s</code> Use a <small>small</small> (11 point) font + + <li><code>@b</code> Use a <b>bold</b> font (adds FL_BOLD to font) + + <li><code>@i</code> Use an <i>italic</i> font (adds FL_ITALIC to font) + + <li><code>@f</code> or <code>@t</code> Use a <code>fixed-pitch</code> + font (sets font to FL_COURIER) + + <li><code>@c</code> Center the line horizontally + + <li><code>@r</code> Right-justify the text + + <li><code>@B0, @B1, ... @B255</code> Fill the backgound with fl_color(n) + + <li><code>@C0, @C1, ... @C255</code> Use fl_color(n) to draw the text + + <li><code>@F0, @F1, ... </code> Use fl_font(n) to draw the text + + <li><code>@S1, @S2, ... </code> Use point size n to draw the text + + <li><code>@u</code> or <code>@_</code> Underline the text. + + <li><code>@-</code> draw an engraved line through the middle. +</ul> + +Notice that the <code>@.</code> 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 <tt>c</tt>. Set the prefix +to 0 to disable formatting. + +<h4><a name="Fl_Browser.hide">void Fl_Browser::hide(int n)</a></h4> + +Makes line <tt>n</tt> invisible, preventing selection by the user. The line +can still be selected under program control. + +<h4><a name="Fl_Browser.insert">void Fl_Browser::insert(int n, const char *, void * = 0)</a></h4> + +Insert a new line <i>before</i> line <tt>n</tt>. If <tt>n</tt> > +<tt>size()</tt> then the line is added to the end. + +<h4><a name="Fl_Browser.load">int Fl_Browser::load(const char *filename)</a></h4> + +Clears the browser and reads the file, adding each line from the file +to the browser. If the filename is <tt>NULL</tt> or a zero-length +string then this just clears the browser. This returns zero if there +was any error in opening or reading the file, in which case +<tt>errno</tt> is set to the system error. The <tt>data()</tt> of each +line is set to <tt>NULL</tt>. + +<h4><a name="Fl_Browser.move">void Fl_Browser::move(int to, int from)</a></h4> + +Line <tt>from</tt> is removed and reinserted at <tt>to</tt>; <tt>to</tt> +is calculated after the line is removed. + +<h4><a name="Fl_Browser.position">int Fl_Browser::position() const<br> +void Fl_Browser::position(int p)</a></h4> + +The first form returns the current vertical scrollbar position, where 0 +corresponds to the top. If there is not vertical scrollbar then this +will always return 0. + +<h4><a name="Fl_Browser.remove">void Fl_Browser::remove(int n)</a></h4> + +Remove line <tt>n</tt> and make the browser one line shorter. + +<h4><a name="Fl_Browser.show">void Fl_Browser::show(int n)</a></h4> + +Makes line <tt>n</tt> visible for selection. + +<h4><a name="Fl_Browser.size">int Fl_Browser::size() const</a></h4> + +Returns how many lines are in the browser. The last line number is +equal to this. + +<h4><a name="Fl_Browser.text">const char *Fl_Browser::text(int n) const<br> +void Fl_Browser::text(int n, const char *)</a></h4> + +The first form returns the text for line <tt>n</tt>. If <tt>n</tt> is +out of range it returns <tt>NULL</tt>. + +<p>The second form sets the text for line <tt>n</tt>. + +<h4><a name="Fl_Browser.topline">int Fl_Browser::topline() const<br> +void Fl_Browser::topline(int n)</a></h4> + +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 sets the top line in the browser to <tt>n</tt>. + +<p>The second form sets the vertical scrollbar position to <tt>p</tt>. + +<h4><a name="Fl_Browser.visible">int Fl_Browser::visible(int n) const</a></h4> + +Returns a non-zero value if line <tt>n</tt> is visible. + +</body> +</html> diff --git a/documentation/Fl_Browser_.html b/documentation/Fl_Browser_.html new file mode 100644 index 000000000..fc8456f51 --- /dev/null +++ b/documentation/Fl_Browser_.html @@ -0,0 +1,171 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Browser_">class Fl_Browser_</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Browser_</b> + | + +----<a href="#Fl_Browser">Fl_Browser</a> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Browser_.H> +</pre></ul> + +<h3>Description</h3> + +This is the base class for browsers. To be useful it must be +subclassed and several virtual functions defined. The Forms-compatable +browser and the file chooser's browser are subclassed off of this. + +<p>This has been designed so that the subclass has complete control +over the storage of the data, although because <tt>next()</tt> and +<tt>prev()</tt> functions are used to index, it works best as a linked +list or as a large block of characters in which the line breaks must be +searched for. + +<p>A great deal of work has been done so that the "height" of a data +object does not need to be determined until it is drawn. This is +useful if actually figuring out the size of an object requires +accessing image data or doing <tt>stat()</tt> on a file or doing some +other slow operation. + +<h3>Methods</h3> + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Browser_.Fl_Browser_">Fl_Browser_</a> + <li><a href="#Fl_Browser_.~Fl_Browser_">~Fl_Browser_</a> + <li><a href="#Fl_Browser_.bbox">bbox</a> + <li><a href="#Fl_Browser_.deleting">deleting</a> + <li><a href="#Fl_Browser_.deselect">deselect</a> + <li><a href="#Fl_Browser_.display">display</a> + <li><a href="#Fl_Browser_.displayed">displayed</a> + <li><a href="#Fl_Browser_.draw">draw</a> + <li><a href="#Fl_Browser_.find_item">find_item</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Browser_.full_height">full_height</a> + <li><a href="#Fl_Browser_.full_width">full_width</a> + <li><a href="#Fl_Browser_.handle">handle</a> + <li><a href="#Fl_Browser_.has_scrollbar">has_scrollbar</a> + <li><a href="#Fl_Browser_.hposition">hposition</a> + <li><a href="#Fl_Browser_.incr_height">incr_height</a> + <li><a href="#Fl_Browser_.inserting">inserting</a> + <li><a href="#Fl_Browser_.item_draw">item_draw</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Browser_.item_first">item_first</a> + <li><a href="#Fl_Browser_.item_height">item_height</a> + <li><a href="#Fl_Browser_.item_next">item_next</a> + <li><a href="#Fl_Browser_.item_prev">item_prev</a> + <li><a href="#Fl_Browser_.item_quick_height">item_quick_height</a> + <li><a href="#Fl_Browser_.item_select">item_select</a> + <li><a href="#Fl_Browser_.item_selected">item_selected</a> + <li><a href="#Fl_Browser_.item_width">item_width</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Browser_.leftedge">leftedge</a> + <li><a href="#Fl_Browser_.new_list">new_list</a> + <li><a href="#Fl_Browser_.position">position</a> + <li><a href="#Fl_Browser_.redraw_line">redraw_line</a> + <li><a href="#Fl_Browser_.redraw_lines">redraw_lines</a> + <li><a href="#Fl_Browser_.replacing">replacing</a> + <li><a href="#Fl_Browser_.resize">resize</a> + <li><a href="#Fl_Browser_.scrollbar_left">scrollbar_left</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Browser_.scrollbar_right">scrollbar_right</a> + <li><a href="#Fl_Browser_.select">select</a> + <li><a href="#Fl_Browser_.select_only">select_only</a> + <li><a href="#Fl_Browser_.selection">selection</a> + <li><a href="#Fl_Browser_.textcolor">textcolor</a> + <li><a href="#Fl_Browser_.textfont">textfont</a> + <li><a href="#Fl_Browser_.textsize">textsize</a> + <li><a href="#Fl_Browser_.top">top</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4><a name="Fl_Browser_.Fl_Browser_">Fl_Browser::Fl_Browser(int, int, int, int, const char * = 0)</a></h4> + +The constructor makes an empty browser. + +<h4><a name="Fl_Browser_.~Fl_Browser_">Fl_Browser::~Fl_Browser(void)</a></h4> + +The destructor deletes all list items and destroys the browser. + +<h4><a name="Fl_Browser_.has_scrollbar">void Fl_Browser_::has_scrollbar(int h)</a></h4> + +By default you can scroll in both directions, and the scrollbars +disappear if the data will fit in the widget. has_scrollbar() +changes this based on the value of <tt>h</tt>: + +<ul> + <li><code>0</code> - No scrollbars + + <li><code>Fl_Browser_::HORIZONTAL</code> - Only a horizontal scrollbar. + + <li><code>Fl_Browser_::VERTICAL</code> - Only a vertical scrollbar. + + <li><code>Fl_Browser_::BOTH</code> - The default is both scrollbars. + + <li><code>Fl_Browser_::HORIZONTAL_ALWAYS</code> - Horizontal + scrollbar always on, vertical always off. + + <li><code>Fl_Browser_::VERTICAL_ALWAYS</code> - Vertical + scrollbar always on, horizontal always off. + + <li><code>Fl_Browser_::BOTH_ALWAYS</code> - Both always on. +</ul> + +<h4><a name="Fl_Browser_.textcolor">Fl_Color Fl_Browser_::textcolor() const<br> +void Fl_Browser_::textcolor(Fl_Color color)</a></h4> + +The first form gets the default text color for the lines in the +browser. + +<p>The second form sets the default text color to <tt>color</tt> + +<h4><a name="Fl_Browser_.textfont">Fl_Font Fl_Browser_::textfont() const<br> +void Fl_Browser_::textfont(Fl_Font font)</a></h4> + +The first form gets the default text font for the lines in the +browser. + +<p>The second form sets the default text font to <tt>font</tt> + +<h4><a name="Fl_Browser_.textsize">uchar Fl_Browser_::textsize() const<br> +void Fl_Browser_::textsize(uchar size)</a></h4> + +The first form gets the default text size for the lines in the +browser. + +<p>The second form sets the default text size to <tt>size</tt> + +</body> +</html> diff --git a/documentation/Fl_Button.html b/documentation/Fl_Button.html new file mode 100644 index 000000000..3ed301853 --- /dev/null +++ b/documentation/Fl_Button.html @@ -0,0 +1,176 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Button">class Fl_Button</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Button</b> + | + +----<a href="#Fl_Check_Button">Fl_Check_Button</a>, <a href="#Fl_Light_Button">Fl_Light_Button</a>, <a href="#Fl_Repeat_Button">Fl_Repeat_Button</a>, + <a href="#Fl_Return_Button">Fl_Return_Button</a>, <a href="#Fl_Round_Button">Fl_Round_Button</a> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Button.H> +</pre></ul> + +<h3>Description</h3> + +<p>Buttons generate callbacks when they are clicked by the user. You +control exactly when and how by changing the values for <tt>type()</tt> and +<tt>when()</tt>. + +<p>Buttons can also generate callbacks in response to +<tt>FL_SHORTCUT</tt> events. The button can either have an explicit +<a href="#Fl_Button.shortcut"><tt>shortcut()</tt></a> value or a letter +shortcut can be indicated in the <tt>label()</tt> with an '&' character +before it. For the label shortcut it does not matter if <i>Alt</i> is +held down, but if you have an input field in the same window, the user +will have to hold down the <i>Alt</i> key so that the input field does +not eat the event first as an <tt>FL_KEYBOARD</tt> event. + +<h3>Methods</h3> + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Button.Fl_Button">Fl_Button</a> + <li><a href="#Fl_Button.~Fl_Button">~Fl_Button</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Button.clear">clear</a> + <li><a href="#Fl_Button.down_box">down_box</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Button.set">set</a> + <li><a href="#Fl_Button.setonly">setonly</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Button.shortcut">shortcut</a> + <li><a href="#Fl_Button.type">type</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Button.value">value</a> + <li><a href="#Fl_Button.when">when</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4><a name="Fl_Button.Fl_Button">Fl_Button::Fl_Button(int x, int y, int w, int h, const char *label = 0)</a></h4> + +The constructor creates the button using the position, size, and label. + +<h4><a name="Fl_Button.~Fl_Button">Fl_Button::~Fl_Button(void)</a></h4> + +The destructor removed the button. + +<h4><a name="Fl_Button.clear">int Fl_Button::clear()</a></h4> + +Same as <tt>value(0)</tt>. + +<h4><a name="Fl_Button.down_box">Fl_Boxtype Fl_Button::down_box() const<br> +void Fl_Button::down_box(Fl_Boxtype bt)</a></h4> + +The first form returns the current down box type, which is drawn when +<tt>value()</tt> is non-zero. + +<p>The second form sets the down box type. The default value of 0 +causes FLTK to figure out the correct matching down version of +<tt>box()</tt>. + +<h4><a name="Fl_Button.set">int Fl_Button::set()</a></h4> + +Same as <tt>value(1)</tt>. + +<h4><a name="Fl_Button.setonly">void Fl_Button::setonly()</a></h4> + +Turns on this button and turns off all other radio buttons in the +group (calling <tt>value(1)</tt> or <tt>set()</tt> does not do this). + +<h4><a name="Fl_Button.shortcut">ulong Fl_Button::shortcut() const<br> +void Fl_Button::shortcut(ulong key)</a></h4> + +The first form returns the current shortcut key for the button. + +<P>The second form sets the shortcut key to <tt>key</tt>. Setting this +overrides the use of '&' in the <tt>label()</tt>. The value is a +bitwise OR of a key and a set of shift flags, for example <code>FL_ALT +| 'a'</code>, <code>FL_ALT | (FL_F + 10)</code>, or just +<code>'a'</code>. A value of 0 disables the shortcut. + +<p>The key can be any value returned by <a href=#event_key><tt> +Fl::event_key()</tt></a>, but will usually be an ASCII letter. Use a +lower-case letter unless you require the shift key to be held down. + +<p>The shift flags can be any set of values accepted by +<a href=#event_state><tt>Fl::event_state()</tt></a>. If the bit is on +that shift key must be pushed. Meta, Alt, Ctrl, and Shift must be off +if they are not in the shift flags (zero for the other bits indicates +a "don't care" setting). + +<h4><a name="Fl_Button.type">uchar Fl_Button::type() const<br> +void Fl_Button::type(uchar t)</a></h4> + +The first form of <tt>type()</tt> returns the current button type, +which can be one of: + +<ul> + <li><code>0</code>: The value is unchanged. + + <li><code>FL_TOGGLE_BUTTON</code>: The value is inverted. + + <li><code>FL_RADIO_BUTTON</code>: The value is set to 1, and all + other buttons in the current group with + <code>type() == FL_RADIO_BUTTON</code> are set to zero. +</ul> + +The second form sets the button type to <tt>t</tt>. + +<h4><a name="Fl_Button.value">char Fl_Button::value() const<br> +int Fl_Button::value(int)</a></h4> + +The first form returns the current value (0 or 1). The second form sets +the current value. + +<h4><a name="Fl_Button.when">Fl_When Fl_Widget::when() const<br> +void Fl_Widget::when(Fl_When w)</a></h4> + +Controls when callbacks are done. The following values are useful, +the default value is <code>FL_WHEN_RELEASE</code>: + +<ul> + <li><code>0</code>: The callback is not done, instead changed() is + turned on. + + <li><code>FL_WHEN_RELEASE</code>: The callback is done after the user + successfully clicks the button, or when a shortcut is typed. + + <li><code>FL_WHEN_CHANGED </code>: The callback is done each time the + value() changes (when the user pushes and releases the button, and as + the mouse is dragged around in and out of the button). +</ul> + +</body> +</html> diff --git a/documentation/Fl_Chart.html b/documentation/Fl_Chart.html new file mode 100644 index 000000000..5a9d527ab --- /dev/null +++ b/documentation/Fl_Chart.html @@ -0,0 +1,162 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Chart">class Fl_Chart</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Chart</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Chart.H> +</pre></ul> + +<h3>Description</h3> + +This widget displays simple charts and is provided for forms compatibility. + +<h3>Methods</h3> + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Chart.Fl_Chart">Fl_Chart</a> + <li><a href="#Fl_Chart.~Fl_Chart">~Fl_Chart</a> + <li><a href="#Fl_Chart.add">add</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Chart.autosize">autosize</a> + <li><a href="#Fl_Chart.bounds">bounds</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Chart.clear">clear</a> + <li><a href="#Fl_Chart.insert">insert</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Chart.maxsize">maxsize</a> + <li><a href="#Fl_Chart.replace">replace</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Chart.size">size</a> + <li><a href="#Fl_Chart.type">type</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4><a name="Fl_Chart.Fl_Chart">Fl_Chart::Fl_Chart(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Chart</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_NO_BOX</tt>. + +<h4><a name="Fl_Chart.~Fl_Chart">virtual Fl_Chart::~Fl_Chart()</a></h4> + +Destroys the <tt>Fl_Chart</tt> widget and all of its data. + +<h4><a name="Fl_Chart.add">void add(double value, const char *label = NULL, uchar color = 0)</a></h4> + +The <tt>add</tt> method adds the <tt>value</tt> and optionally <tt>label</tt> +and <tt>color</tt> to the chart. + +<h4><a name="Fl_Chart.autosize">uchar autosize(void) const<br> +void autosize(uchar onoff)</a></h4> + +The <tt>autosize</tt> method controls whether or not the chart will +automatically adjust the bounds of the chart. The first form returns a +boolean value that is non-zero if auto-sizing is enabled and zero is auto-sizing +is disabled. + +<p>The second form of <tt>autosize</tt> sets the auto-sizing property to +<tt>onoff</tt>. + +<h4><a name="Fl_Chart.bounds">void bounds(double *a, double *b)<br> +void bounds(double a, double b)</a></h4> + +The <tt>bounds</tt> method gets or sets the lower and upper bounds of the chart +values to <tt>a</tt> and <tt>b</tt> respectively. + +<h4><a name="Fl_Chart.clear">void clear(void)</a></h4> + +The <tt>clear</tt> method removes all values from the chart. + +<h4><a name="Fl_Chart.insert">void insert(int pos, double value, const char *label = NULL, uchar color = 0)</a></h4> + +The <tt>insert</tt> method inserts a data value at the given position +<tt>pos</tt>. Position 0 is the first data value. + +<h4><a name="Fl_Chart.maxsize">int maxsize(void) const<br> +void maxsize(int n)</a></h4> + +The <tt>maxsize</tt> method gets or sets the maximum number of data values for +a chart. + +<h4><a name="Fl_Chart.replace">void replace(int pos, double value, const char *label = NULL, uchar color = 0)</a></h4> + +The <tt>replace</tt> method replaces data value <tt>pos</tt> with +<tt>value</tt>, <tt>label</tt>, and <tt>color</tt>. Position 0 is +the first data value. + +<h4><a name="Fl_Chart.size">int size(void) const</a></h4> + +The <tt>size</tt> method returns the number of data values in the chart. + +<h4><a name="Fl_Chart.type">uchar type() const<br> +void type(uchar t)</a></h4> + +The first form of <tt>type()</tt> returns the current chart type. +The chart type can be one of the following: + +<DL> + <DT>FL_BAR_CHART</DT> + <DD>Each sample value is drawn as a vertical bar.</DD> + + <DT>FL_FILLED_CHART</DT> + <DD>The chart is filled from the bottom of the graph to the + sample values.</DD> + + <DT>FL_HORBAR_CHART</DT> + <DD>Each sample value is drawn as a horizontal bar.</DD> + + <DT>FL_LINE_CHART</DT> + <DD>The chart is drawn as a polyline with vertices at each + sample value.</DD> + + <DT>FL_PIE_CHART</DT> + <DD>A pie chart is drawn with each sample value being drawn + as a proportionate slice in the circle.</DD> + + <DT>FL_SPECIALPIE_CHART</DT> + <DD>Like FL_PIE_CHART, but the first slice is separated from + the pie.</DD> + + <DT>FL_SPIKE_CHART</DT> + <DD>Each sample value is drawn as a vertical line.</DD> +</DL> + +The second form of <tt>type()</tt> sets the chart type to <tt>t</tt>. + +<center><img src="charts.gif" width=80%></center> + +</body> +</html> diff --git a/documentation/Fl_Check_Button.html b/documentation/Fl_Check_Button.html new file mode 100644 index 000000000..14ac7f0eb --- /dev/null +++ b/documentation/Fl_Check_Button.html @@ -0,0 +1,53 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Check_Button">class Fl_Check_Button</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Button">Fl_Button</a> + | + +----<b>Fl_Check_Button</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Check_Button.H> +</pre></ul> + +<h3>Description</h3> + +Buttons generate callbacks when they are clicked by the user. You +control exactly when and how by changing the values for <tt>type()</tt> and +<tt>when()</tt>. + +<P>The <tt>Fl_Check_Button</tt> subclass display the "on" state by +turning on a light, rather than drawing pushed in. The shape of the +"light" is initially set to FL_DIAMOND_DOWN_BOX. The color of the +light when on is controlled with <tt>selection_color()<tt>, which defaults to +FL_RED. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Check_Button.Fl_Check_Button">Fl_Check_Button</a> + <li><a href="#Fl_Check_Button.~Fl_Check_Button">~Fl_Check_Button</a> +</ul> + +<h4><a name="Fl_Check_Button.Fl_Check_Button">Fl_Check_Button::Fl_Check_Button(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Check_Button</tt> widget using the given position, +size, and label string. + +<h4><a name="Fl_Check_Button.~Fl_Check_Button">Fl_Check_Button::~Fl_Check_Button()</a></h4> + +The destructor deletes the check button. + +</body> +</html> diff --git a/documentation/Fl_Choice.html b/documentation/Fl_Choice.html new file mode 100644 index 000000000..96b4337dc --- /dev/null +++ b/documentation/Fl_Choice.html @@ -0,0 +1,110 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Choice">class Fl_Choice</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Menu_">Fl_Menu_</a> + | + +----<b>Fl_Choice</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Choice.H> +</pre></ul> + +<h3>Description</h3> + +This is a button that when pushed pops up a menu (or hierarchy of +menus) defined by an array of <a href="#Fl_Menu_Item"><tt>Fl_Menu_Item</tt></a> +objects. Motif calls this an OptionButton. + +<p>The only difference between this and a <a href="#Fl_Menu_Button"> +<tt>Fl_Menu_Button</tt></a> is that the name of the most recent chosen +menu item is displayed inside the box, while the label is displayed +outside the box. However, since the use of this is most often to +control a single variable rather than do individual callbacks, some of +the <tt>Fl_Menu_Button</tt> methods are redescribed here in those terms. + +<P>When the user picks an item off the menu the <tt>value()</tt> is set +to that item and then the callback is done. + +<p>All three mouse buttons pop up the menu. The Forms behavior of the +first two buttons to increment/decrement the choice is not +implemented. This could be added with a subclass, however. + +<p>The menu will also pop up in response to shortcuts indicated by +putting a '&' character in the <tt>label()</tt>. See +<a href="#Fl_Button"><tt>Fl_Button</tt></a> for a description of this. + +<p>Typing the <tt>shortcut()</tt> of any of the items will do exactly +the same as when you pick the item with the mouse. The '&' character +in item names are only looked at when the menu is popped up, however. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Choice.Fl_Choice">Fl_Choice</a> + <li><a href="#Fl_Choice.~Fl_Choice">~Fl_Choice</a> + <li><a href="#Fl_Choice.clear_changed">clear_changed</a> + <li><a href="#Fl_Choice.changed">changed</a> + <li><a href="#Fl_Choice.down_box">down_box</a> + <li><a href="#Fl_Choice.set_changed">set_changed</a> + <li><a href="#Fl_Choice.value">value</a> +</ul> + +<h4><a name="Fl_Choice.Fl_Choice">Fl_Choice::Fl_Choice(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Choice</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_UP_BOX</tt>. + +<p>The constructor sets <tt>menu()</tt> to <tt>NULL</tt>. See <a +href="#Fl_Menu_"><tt>Fl_Menu_</tt></a> for the methods to set or change +the menu. + +<h4><a name="Fl_Choice.~Fl_Choice">virtual Fl_Choice::~Fl_Choice()</a></h4> + +The destructor removes the <tt>Fl_Choice</tt> widget and all of its menu items. + +<h4><a name="Fl_Choice.value">int Fl_Choice::value() const<br> +int Fl_Choice::value(int)<br> +int Fl_Choice::value(const Fl_Menu *)</a></h4> + +The value is the index into the <tt>Fl_Menu</tt> array of the last item chosen +by the user. It is zero initially. You can set it as an integer, or +set it with a pointer to a menu item. The set routines return +non-zero if the new value is different than the old one. Changing it +causes a <tt>redraw()</tt>. + +<h4><a name="Fl_Choice.changed">int Fl_Widget::changed() const</a></h4> + +This value is true if the user picks a different value. <i>It is +turned off by <tt>value()</tt> and just before doing a callback (the +callback can turn it back on if desired).</i> + +<h4><a name="Fl_Choice.set_changed">void Fl_Widget::set_changed()</a></h4> + +This method sets the <tt>changed()</tt> flag. + +<h4><a name="Fl_Choice.clear_changed">void Fl_Widget::clear_changed()</a></h4> + +This method clears the <tt>changed()</tt> flag. + +<h4><a name="Fl_Choice.down_box">Fl_Boxtype Fl_Choice::down_box() const<br> +void Fl_Choice::down_box(Fl_Boxtype b)</a></h4> + +The first form gets the current down box, which is used when the menu +is popped up. The default down box type is <tt>FL_DOWN_BOX</tt> + +The second form sets the current down box type to <tt>b</tt>. + +</body> +</html> diff --git a/documentation/Fl_Clock.html b/documentation/Fl_Clock.html new file mode 100644 index 000000000..e1da8a9e9 --- /dev/null +++ b/documentation/Fl_Clock.html @@ -0,0 +1,78 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Clock">class Fl_Clock</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Clock</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Clock.H> +</pre></ul> + +<h3>Description</h3> + +This widget provides a round analog clock display and is provided for +Forms compatibility. It installs a 1-second timeout callback using +<a href="#add_timeout"><tt>Fl::add_timeout()</tt></a>. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Clock.Fl_Clock">Fl_Clock</a> + <li><a href="#Fl_Clock.~Fl_Clock">~Fl_Clock</a> + <li><a href="#Fl_Clock.hour">hour</a> + <li><a href="#Fl_Clock.minute">minute</a> + <li><a href="#Fl_Clock.second">second</a> + <li><a href="#Fl_Clock.value">value</a> +</ul> + +<h4><a name="Fl_Clock.Fl_Clock">Fl_Clock::Fl_Clock(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Clock</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_NO_BOX</tt>. + +<h4><a name="Fl_Clock.~Fl_Clock">virtual Fl_Clock::~Fl_Clock()</a></h4> + +The destructor <i>also deletes all the children</i>. This allows a +whole tree to be deleted at once, without having to keep a pointer to all +the children in the user code. A kludge has been done so the +<tt>Fl_Clock</tt> and all of it's children can be automatic (local) +variables, but you must declare the <tt>Fl_Clock</tt> <i>first</i>, so +that it is destroyed last. + +<h4><a name="Fl_Clock.hour">int Fl_Clock::hour() const</a></h4> + +Returns the current hour (0 to 23). + +<h4><a name="Fl_Clock.minute">int Fl_Clock::minute() const</a></h4> + +Returns the current minute (0 to 59). + +<h4><a name="Fl_Clock.second">int Fl_Clock::second() const</a></h4> + +Returns the current second (0 to 60, 60 = leap second). + +<h4><a name="Fl_Clock.value">void Fl_Clock::value(ulong v)<br> +void Fl_Clock::value(int h, int m, int s)<br> +ulong Fl_Clock::value(void)</a></h4> + +The first two forms of <tt>value</tt> set the displayed time to the given +UNIX time value or specific hours, minutes, and seconds. + +<p>The third form of <tt>value</tt> returns the displayed time in seconds +since the UNIX epoch (January 1, 1970). + +</body> +</html> diff --git a/documentation/Fl_Color_Chooser.html b/documentation/Fl_Color_Chooser.html new file mode 100644 index 000000000..5f9a0ed53 --- /dev/null +++ b/documentation/Fl_Color_Chooser.html @@ -0,0 +1,103 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Color_Chooser">class Fl_Color_Chooser</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Group">Fl_Group</a> + | + +----<b>Fl_Color_Chooser</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Color_Chooser.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Color_Chooser</tt> widget provides a standard RGB color +chooser. You can place any number of these into a panel of your own +design. This widget contains the hue box, value slider, and rgb input +fields from the above diagram (it does not have the color chips or the +Cancel or OK buttons). The callback is done every time the user +changes the rgb value. It is not done if they move the hue control in +a way that produces the <i>same</i> rgb value, such as when saturation +or value is zero. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Color_Chooser.Fl_Color_Chooser">Fl_Color_Chooser</a> + <li><a href="#Fl_Color_Chooser.~Fl_Color_Chooser">~Fl_Color_Chooser</a> + <li><a href="#Fl_Color_Chooser.add">add</a> +</ul> + +<h4><a name="Fl_Color_Chooser.Fl_Color_Chooser">Fl_Color_Chooser::Fl_Color_Chooser(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Color_Chooser</tt> widget using the given +position, size, and label string. The recommended dimensions are +200x95. The color is initialized to black. + +<h4><a name="Fl_Color_Chooser.~Fl_Color_Chooser">virtual Fl_Color_Chooser::~Fl_Color_Chooser()</a></h4> + +The destructor removes the color chooser and all of its controls. + +<h4><a name="Fl_Color_Chooser.hue">double Fl_Color_Chooser::hue() const</a></h4> + +Return the current hue. 0 <= hue < 6. Zero is red, one is +yellow, two is green, etc. <i>This value is convienent for the internal +calculations - some other systems consider hue to run from zero to +one, or from 0 to 360.</i> + +<h4><a name="Fl_Color_Chooser.saturation">double Fl_Color_Chooser::saturation() const</a></h4> + +Returns the saturation. 0 <= saturation <= 1. + +<h4><a name="Fl_Color_Chooser.value">double Fl_Color_Chooser::value() const</a></h4> + +Returns the value/brightness. 0 <= value <= 1. + +<h4><a name="Fl_Color_Chooser.r">double Fl_Color_Chooser::r() const</a></h4> + +Returns the current red value. 0 <= r <= 1. + +<h4><a name="Fl_Color_Chooser.g">double Fl_Color_Chooser::g() const</a></h4> + +Returns the current green value. 0 <= g <= 1. + +<h4><a name="Fl_Color_Chooser.b">double Fl_Color_Chooser::b() const</a></h4> + +Returns the current blue value. 0 <= b <= 1. + +<h4><a name="Fl_Color_Chooser.rgb">int Fl_Color_Chooser::rgb(double, double, +double)</a></h4> + +Sets the current rgb color values. Does not do the callback. Does +not clamp (but out of range values will produce psychedelic effects in +the hue selector). + +<h4><a name="Fl_Color_Chooser.hsv">int Fl_Color_Chooser::hsv(double,double,double)</a></h4> + +Set the hsv values. The passed values are clamped (or for hue, +modulus 6 is used) to get legal values. Does not do the callback. + +<h4><a name="Fl_Color_Chooser.hsv2rgb">static void Fl_Color_Chooser::hsv2rgb(double, double, +double, double&, double&, double&)</a></h4> + +This <i>static</i> method converts HSV colors to RGB colorspace. + +<h4><a name="Fl_Color_Chooser.rgb2hsv">static void Fl_Color_Chooser::rgb2hsv(double, double, double, double&, +double&, double&)</a></h4> + +This <i>static</i> method converts RGB colors to HSV colorspace. + +</body> +</html> diff --git a/documentation/Fl_Counter.html b/documentation/Fl_Counter.html new file mode 100644 index 000000000..42551fefa --- /dev/null +++ b/documentation/Fl_Counter.html @@ -0,0 +1,66 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Counter">class Fl_Counter</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Valuator">Fl_Valuator</a> + | + +----<b>Fl_Counter</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Counter.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Counter</tt> widget is provided for forms compatibility. It +controls a single floating point value. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Counter.Fl_Counter">Fl_Counter</a> + <li><a href="#Fl_Counter.~Fl_Counter">~Fl_Counter</a> + <li><a href="#Fl_Counter.lstep">lstep</a> + <li><a href="#Fl_Counter.type">type</a> +</ul> + +<h4><a name="Fl_Counter.Fl_Counter">Fl_Counter::Fl_Counter(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Counter</tt> widget using the given position, size, and +label string. The default type is <tt>FL_NORMAL_COUNTER</tt>. + +<h4><a name="Fl_Counter.~Fl_Counter">virtual Fl_Counter::~Fl_Counter()</a></h4> + +Destroys the valuator. + +<h4><a name="Fl_Counter.lstep">double Fl_Counter::lstep() const<br> +void Fl_Counter::lstep(double)</a></h4> + +Get or set the increment for the double-arrow buttons. The default +value is 1.0. + +<h4><a name="Fl_Counter.type">type(uchar)</a></h4> + +Sets the type of counter: + +<ul> + <li><tt>FL_NORMAL_COUNTER</tt> - Displays a counter with 4 arrow + buttons. + + <li><tt>FL_SIMPLE_COUNTER</tt> - Displays a counter with only 2 + arrow buttons. +</ul> + +</body> +</html> diff --git a/documentation/Fl_Dial.html b/documentation/Fl_Dial.html new file mode 100644 index 000000000..2e732440a --- /dev/null +++ b/documentation/Fl_Dial.html @@ -0,0 +1,65 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Dial">class Fl_Dial</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Valuator">Fl_Valuator</a> + | + +----<b>Fl_Dial</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Dial.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Dial</tt> widget provides a circular dial to control a +single floating point value. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Dial.Fl_Dial">Fl_Dial</a> + <li><a href="#Fl_Dial.~Fl_Dial">~Fl_Dial</a> + <li><a href="#Fl_Dial.angles">angles</a> + <li><a href="#Fl_Dial.type">type</a> +</ul> + +<h4><a name="Fl_Dial.Fl_Dial">Fl_Dial::Fl_Dial(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Dial</tt> widget using the given position, size, and +label string. The default type is <tt>FL_NORMAL_DIAL</tt>. + +<h4><a name="Fl_Dial.~Fl_Dial">virtual Fl_Dial::~Fl_Dial()</a></h4> + +Destroys the valuator. + +<h4><a name="Fl_Dial.angles">void Fl_Dial::angles(short a, short b)</a></h4> + +Sets the angles used for the minimum and maximum values. By default these +are 0 and 360, respectively. + +<h4><a name="Fl_Dial.type">type(uchar)</a></h4> + +Sets the type of the dial to: + +<ul> + <li><tt>FL_NORMAL_DIAL</tt> - Draws a normal dial with a knob. + + <li><tt>FL_LINE_DIAL</tt> - Draws a dial with a line. + + <li><tt>FL_FILL_DIAL</tt> - Draws a dial with a filled arc. +</tt> + +</body> +</html> diff --git a/documentation/Fl_Double_Window.html b/documentation/Fl_Double_Window.html new file mode 100644 index 000000000..9018b850c --- /dev/null +++ b/documentation/Fl_Double_Window.html @@ -0,0 +1,66 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Double_Window">class Fl_Double_Window</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Window">Fl_Window</a> + | + +----<b>Fl_Double_Window</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Double_Window.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Double_Window</tt> class provides a double-buffered window. +If possible this will use the X double buffering extension (Xdbe). If +not, it will draw the window data into an off-screen pixmap, and then +copy it to the on-screen window. + +<p>It is highly recommended that you put the following code before the +first <tt>show()</tt> of <i>any</i> window in your program: + +<ul><pre> +Fl::visual(FL_DOUBLE|FL_INDEX) +</pre></ul> + +This makes sure you can use Xdbe on servers where double buffering does +not exist for every visual. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Double_Window.Fl_Double_Window">Fl_Double_Window</a> + <li><a href="#Fl_Double_Window.~Fl_Double_Window">~Fl_Double_Window</a> + <li><a href="#Fl_Double_Window.pixmap">pixmap</a> +</ul> + +<h4><a name="Fl_Double_Window.Fl_Double_Window">Fl_Double_Window::Fl_Double_Window(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Double_Window</tt> widget using the given position, size, and +label (title) string. + +<h4><a name="Fl_Double_Window.~Fl_Double_Window">virtual Fl_Double_Window::~Fl_Double_Window()</a></h4> + +The destructor <i>also deletes all the children</i>. This allows a +whole tree to be deleted at once, without having to keep a pointer to all +the children in the user code. + +<h4><a name="Fl_Double_Window.pixmap>ulong Fl_Double_Window::pixmap() const</a></h4> + +Returns the off-screen pixmap or back buffer. This value is zero until +the first time <tt>flush()</tt> is called. + +</body> +</html> diff --git a/documentation/Fl_End.html b/documentation/Fl_End.html new file mode 100644 index 000000000..7c21a8db2 --- /dev/null +++ b/documentation/Fl_End.html @@ -0,0 +1,51 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_End">class Fl_End</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Group">Fl_Group</a>----<b>Fl_End</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Group.H> +</pre></ul> + +<h3>Description</h3> + +This is a dummy class that allows you to end a group in a constructor list of a class: + +<ul><pre>class MyClass { + Fl_Group group; + Fl_Button button_in_group; + Fl_End end; + Fl_Button button_outside_group; + MyClass(); +}; +MyClass::MyClass() : + group(10,10,100,100), + button_in_group(20,20,60,30), + end(), + button_outside_group(10,120,60,30) +{}</pre></ul> + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_End.Fl_End">Fl_End</a> +</ul> + +<h4><a name="Fl_End.Fl_End">Fl_End::Fl_End</a></h4> + +The constructor does <tt>Fl_Group::current()->end()</tt>. + +</body> +</html> diff --git a/documentation/Fl_Float_Input.html b/documentation/Fl_Float_Input.html new file mode 100644 index 000000000..ef005b4a8 --- /dev/null +++ b/documentation/Fl_Float_Input.html @@ -0,0 +1,47 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Float_Input">class Fl_Float_Input</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Input">Fl_Input</a> + | + +----<b>Fl_Float_Input</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Input.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Float_Input</tt> class is a subclass of <tt>Fl_Input</tt> that +displays its input in red when the value string is not a legal floating point +value. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Float_Input.Fl_Float_Input">Fl_Float_Input</a> + <li><a href="#Fl_Float_Input.~Fl_Float_Input">~Fl_Float_Input</a> +</ul> + +<h4><a name="Fl_Float_Input.Fl_Float_Input">Fl_Float_Input::Fl_Float_Input(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Float_Input</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_DOWN_BOX</tt>. + +<h4><a name="Fl_Float_Input.~Fl_Float_Input">virtual Fl_Float_Input::~Fl_Float_Input()</a></h4> + +Destroys the widget and any value associated with it. + +</body> +</html> diff --git a/documentation/Fl_Free.html b/documentation/Fl_Free.html new file mode 100644 index 000000000..55616cb30 --- /dev/null +++ b/documentation/Fl_Free.html @@ -0,0 +1,87 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Free">class Fl_Free</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Free</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Free.H> +</pre></ul> + +<h3>Description</h3> + +Emulation of the Forms "free" widget. This emulation allows the free +demo to run, and appears to be useful for porting programs written in +Forms which use the free widget or make subclasses of the Forms widgets. + +<p>There are five types of free, which determine when the handle +function is called: + +<ul><pre> +#define FL_NORMAL_FREE 1 +#define FL_SLEEPING_FREE 2 +#define FL_INPUT_FREE 3 +#define FL_CONTINUOUS_FREE 4 +#define FL_ALL_FREE 5 +</pre></ul> + +<p>An FL_INPUT_FREE accepts FL_FOCUS events. A FL_CONTINUOUS_FREE +sets a timeout callback 100 times a second and provides a FL_STEP +event, this has obvious detrimental effects on machine performance. +FL_ALL_FREE does both. FL_SLEEPING_FREE are deactivated. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Free.Fl_Free">Fl_Free</a> + <li><a href="#Fl_Free.~Fl_Free">~Fl_Free</a> +</ul> + +<h4><a name="Fl_Free.Fl_Free">Fl_Free(uchar type, int, int, int, int, const char*l, FL_HANDLEPTR hdl)</a></h4> + +The constructor takes both the <tt>type</tt> and the <tt>handle</tt> function. +The handle function should be declared as follows: + +<ul><pre> +int +handle_function(Fl_Widget *w, + int event, + float event_x, + float event_y, + char key) +</pre></ul> + +This function is called from the the <tt>handle()</tt> method in +response to most events, and is called by the <tt>draw()</tt> method. +The <tt>event</tt> argument contains the event type: + +<ul><pre> +// old event names for compatability: +#define FL_MOUSE FL_DRAG +#define FL_DRAW 0 +#define FL_STEP 9 +#define FL_FREEMEM 12 +#define FL_FREEZE FL_UNMAP +#define FL_THAW FL_MAP +</pre></ul> + +<h4><a name="Fl_Free.~Fl_Free">virtual Fl_Free::~Fl_Free()</a></h4> + +The destructor will call the handle function with the event +<tt>FL_FREE_MEM</tt>. + +</body> +</html> diff --git a/documentation/Fl_Gl_Window.html b/documentation/Fl_Gl_Window.html new file mode 100644 index 000000000..47828b47c --- /dev/null +++ b/documentation/Fl_Gl_Window.html @@ -0,0 +1,265 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Gl_Window">class Fl_Gl_Window</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Gl_Window</b> + | + +----<a href="#Fl_Pack">Fl_Pack</a>, <a href="#Fl_Scroll">Fl_Scroll</a>, <a href="#Fl_Tabs">Fl_Tabs</a>, <a href="#Fl_Tile">Fl_Tile</a>, <a href="#Fl_Window">Fl_Window</a> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Gl_Window.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Gl_Window</tt> widget sets things up so OpenGL works, and +also keeps an OpenGL "context" for that window, so that changes to the +lighting and projection may be reused between redraws. +</tt>Fl_Gl_Window</tt> also flushes the OpenGL streams and swaps +buffers after <tt>draw()</tt> returns. + +<p>OpenGL hardware typically provides some overlay bit planes, which +are very useful for drawing UI controls atop your 3D graphics. If the +overlay hardware is not provided, FLTK tries to simulate the overlay, +This works pretty well if your graphics are double buffered, but not +very well for single-buffered. + +<h3>Methods</h3> + + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Gl_Window.Fl_Gl_Window">Fl_Gl_Window</a> + <li><a href="#Fl_Gl_Window.~Fl_Gl_Window">~Fl_Gl_Window</a> + <li><a href="#Fl_Gl_Window.can_do">can_do</a> + <li><a href="#Fl_Gl_Window.can_do_overlay">can_do_overlay</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Gl_Window.draw">draw</a> + <li><a href="#Fl_Gl_Window.draw_overlay">draw_overlay</a> + <li><a href="#Fl_Gl_Window.handle">handle</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Gl_Window.hide">hide</a> + <li><a href="#Fl_Gl_Window.invalidate">invalidate</a> + <li><a href="#Fl_Gl_Window.make_current">make_current</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Gl_Window.make_overlay_current">make_overlay_current</a> + <li><a href="#Fl_Gl_Window.mode">mode</a> + <li><a href="#Fl_Gl_Window.ortho">ortho</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Gl_Window.redraw_overlay">redraw_overlay</a> + <li><a href="#Fl_Gl_Window.swap_buffers">swap_buffers</a> + <li><a href="#Fl_Gl_Window.valid">valid</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4><a name="Fl_Gl_Window.Fl_Gl_Window">Fl_Gl_Window::Fl_Gl_Window(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Gl_Window</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_NO_BOX</tt>. The default mode is +<tt>FL_RGB|FL_DOUBLE|FL_DEPTH</tt>. + +<h4><a name="Fl_Gl_Window.~Fl_Gl_Window">virtual Fl_Gl_Window::~Fl_Gl_Window()</a></h4> + +The destructor removes the widget and destroys the OpenGL context associated +with it. + +<h4><a name="Fl_Gl_Window.draw">virtual void Fl_Gl_Window::draw(void)</a></h4> + +<tt>Fl_Gl_Window::draw()</tt> is a pure virtual method. You must +subclass <tt>Fl_Gl_Window</tt> and provide an implementation for +<tt>draw()</tt>. You may also provide an implementation of +draw_overlay() if you want to draw into the overlay planes. You can +avoid reinitializing the viewport and lights and other things by +checking <tt>valid()</tt> at the start of <tt>draw()</tt> and only +doing the initialization if it is false. + +<p>The <tt>draw()</tt> method can <i>only</i> use OpenGL calls. Do not +attempt to call X, any of the functions in <FL/fl_draw.H>, or +<tt>glX</tt> directly. Do not call <tt>gl_start()</tt> or +<tt>gl_finish()</tt>. + +<p>If double-buffering is enabled in the window, the back and front buffers +are swapped after this function is completed. + +<h4><a name="Fl_Gl_Window.mode">const int Fl_Gl_Window::mode() const<br> +int Fl_Gl_Window::mode(int m)</a></h4> + +Set or change the OpenGL capabilites of the window. The value can be +any of the following OR'd together: + +<ul> + <li><tt>FL_RGB</tt> - RGB color (not indexed) + <li><tt>FL_RGB8</tt> - RGB color with at least 8 bits of each color + <li><tt>FL_INDEX</tt> - Indexed mode + <li><tt>FL_SINGLE</tt> - not double buffered + <li><tt>FL_DOUBLE</tt> - double buffered + <li><tt>FL_ACCUM</tt> - accumulation buffer + <li><tt>FL_ALPHA</tt> - alpha channel in color + <li><tt>FL_DEPTH</tt> - depth buffer + <li><tt>FL_STENCIL</tt> - stencil buffer + <li><tt>FL_MULTISAMPLE</tt> - multisample antialiasing +</ul> + +<tt>FL_RGB</tt> and <tt>FL_SINGLE</tt> have a value of zero, so they are +"on" unless you give <tt>FL_INDEX</tt> or <tt>FL_DOUBLE</tt>. + +<p>If the desired combination cannot be done, FLTK will try turning off +<tt>FL_MULTISAMPLE</tt>. If this also fails the <tt>show()</tt> will call +<tt>Fl::error()</tt> and not show the window. + +<p>You can change the mode while the window is displayed. This +is most useful for turning double-buffering on and off. Under +X this will cause the old X window to be destroyed and a new one to be +created. If this is a top-level window this will unfortunately also +cause the window to blink, raise to the top, and be de-iconized, and +the <tt>xid()</tt> will change, possibly breaking other code. It is best to +make the GL window a child of another window if you wish to do this! + +<h4><a name="Fl_Gl_Window.can_do">static int Fl_Gl_Window::can_do(int)<br> +int Fl_Gl_Window::can_do() const</a></h4> + +Returns non-zero if the hardware supports the given or current OpenGL mode. + +<h4><a name="Fl_Gl_Window.valid">char Fl_Gl_Window::valid() const<br> +void Fl_Gl_Window::valid(char i)</a></h4> + +<tt>Fl_Gl_Window::valid()</tt> is turned off when FLTK creates a +new context for this window or when the window resizes, and is turned +on <i>after</i> <tt>draw()</tt> is called. You can use this inside your <tt>draw()</tt> +method to avoid unneccessarily initializing the OpenGL context. Just +do this: + +<ul><pre> +void mywindow::draw() { + if (!valid()) { + glViewport(0,0,w(),h()); + glFrustum(...); + glLight(...); + ...other initialization... + } + ... draw your geometry here ... +} + +<br>void Fl_Gl_Window::invalidate(); +<br>void Fl_Gl_Window::valid(char i);</a></h4> + +<tt>Fl_Gl_Window::valid()</tt> is turned off when FLTK creates a +new context for this window and by the window resizing, and is turned +on <i>after</i> draw() is called. You can use this inside your draw() +method to avoid unneccessarily initializing the OpenGL context. Just +do this: + +<pre><tt>void mywindow::draw() { + if (!valid()) { + glViewport(0,0,w(),h()); + glFrustum(...); + glLight(...); + ...other initilization... + } + ... draw your geometry here ... +} +</pre></ul> + +You can turn <tt>valid()</tt> on by calling <tt>valid(1)</tt>. You +should only do this after fixing the transformation inside a +<tt>draw()</tt> or after <tt>make_current()</tt>. This is done +automatically after <tt>draw()</tt> returns. + +<h4><a name="Fl_Gl_Window.invalidate">void Fl_Gl_Window::invalidate()</a></h4> + +The <tt>invalidate()</tt> method turns off <tt>valid()</tt> and is +equivalent to calling <tt>value(0)</tt>. + +<h4><a name="Fl_Gl_Window.ortho">void Fl_Gl_Window::ortho()</a></h4> + +Set the projection so 0,0 is in the lower left of the window and each +pixel is 1 unit wide/tall. If you are drawing 2D images, your +<tt>draw()</tt> method may want to call this if <tt>valid()</tt> is +false. + +<h4><a name="Fl_Gl_Window.make_current">void Fl_Gl_Window::make_current()</a></h4> + +The <tt>make_current()</tt> method selects the OpenGL context for the +widget. It is called automatically prior to the <tt>draw()</tt> method +being called and can also be used to implement feedback and/or selection +within the <tt>handle()</tt> method. + +<h4><a name="Fl_Gl_Window.make_overlay_current">void Fl_Gl_Window::make_overlay_current()</a></h4> + +The <tt>make_overlay_current()</tt> method selects the OpenGL context +for the widget's overlay. It is called automatically prior to the +<tt>draw_overlay()</tt> method being called and can also be used to +implement feedback and/or selection within the <tt>handle()</tt> +method. + +<h4><a name="Fl_Gl_Window.swap_buffers">void Fl_Gl_Window::swap_buffers()</a></h4> + +The <tt>swap_buffers()</tt> method swaps the back and front buffers. +It is called automatically after the <tt>draw()</tt> method is called. + +<h4><a name="Fl_Gl_Window.hide">void Fl_Gl_Window::hide()</a></h4> + +Hides the window and destroys the OpenGL context. + +<h4><a name="Fl_Gl_Window.can_do_overlay">int Fl_Gl_Window::can_do_overlay()</a></h4> + +Returns true if the hardware overlay is possible. If this is false, +FLTK will try to simulate the overlay, with significant loss of update +speed. Calling this will cause FLTK to open the display. + +<h4><a name="Fl_Gl_Window.redraw_overlay">void Fl_Gl_Window::redraw_overlay()</a></h4> + +This method causes <tt>draw_overlay</tt> to be called at a later time. +Initially the overlay is clear, if you want the window to display +something in the overlay when it first appears, you must call this +immediately after you <tt>show()</tt> your window. + +<h4><a name="Fl_Gl_Window.draw_overlay">virtual void Fl_Gl_Window::draw_overlay()</a></h4> + +You must implement this virtual function if you want to draw into the +overlay. The overlay is cleared before this is called. You should +draw anything that is not clear using OpenGL. You must use +<tt>gl_color(i)</tt> to choose colors (it allocates them from the colormap +using system-specific calls), and remember that you are in an indexed +OpenGL mode and drawing anything other than flat-shaded will probably +not work. + +<p>Both this function and <tt>Fl_Gl_Window::draw()</tt> should check +<tt>Fl_Gl_Window::valid()</tt> and set the same transformation. If you +don't your code may not work on other systems. Depending on the OS, +and on whether overlays are real or simulated, the OpenGL context may +be the same or different between the overlay and main window. + +</body> +</html> diff --git a/documentation/Fl_Group.html b/documentation/Fl_Group.html new file mode 100644 index 000000000..315ce1b37 --- /dev/null +++ b/documentation/Fl_Group.html @@ -0,0 +1,178 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Group">class Fl_Group</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Group</b> + | + +----<a href="#Fl_Pack">Fl_Pack</a>, <a href="#Fl_Scroll">Fl_Scroll</a>, <a href="#Fl_Tabs">Fl_Tabs</a>, <a href="#Fl_Tile">Fl_Tile</a>, <a href="#Fl_Window">Fl_Window</a> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Group.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Group</tt> class is the FLTK container widget. It maintains +an array of child widgets. These children can themselves be any widget +including <tt>Fl_Group</tt>. The most important subclass of <tt>Fl_Group</tt> +is <a href="#Fl_Window"><tt>Fl_Window</tt></a>, however groups can also +be used to control radio buttons or to enforce resize behavior. + +<h3>Methods</h3> + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Group.Fl_Group">Fl_Group</a> + <li><a href="#Fl_Group.~Fl_Group">~Fl_Group</a> + <li><a href="#Fl_Group.add">add</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Group.add_resizable">add_resizable</a> + <li><a href="#Fl_Group.array">array</a> + <li><a href="#Fl_Group.begin">begin</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Group.child">child</a> + <li><a href="#Fl_Group.children">children</a> + <li><a href="#Fl_Group.current">current</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Group.end">end</a> + <li><a href="#Fl_Group.find">find</a> + <li><a href="#Fl_Group.insert">insert</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Group.remove">remove</a> + <li><a href="#Fl_Group.resizeable">resizable</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4><a name="Fl_Group.Fl_Group">Fl_Group::Fl_Group(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Group</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_NO_BOX</tt>. + +<h4><a name="Fl_Group.~Fl_Group">virtual Fl_Group::~Fl_Group()</a></h4> + +The destructor <i>also deletes all the children</i>. This allows a +whole tree to be deleted at once, without having to keep a pointer to all +the children in the user code. A kludge has been done so the +<tt>Fl_Group</tt> and all of it's children can be automatic (local) +variables, but you must declare the <tt>Fl_Group</tt> <i>first</i>, so +that it is destroyed last. + +<h4><a name="Fl_Group.add">void Fl_Group::add(Fl_Widget &w)<BR> +void Fl_Group::add(Fl_Widget *w)</a></h4> + +Adds a widget to the group at the end of the child array. + +<h4><a name="Fl_Group.add_resizable">Fl_Group &Fl_Group::add_resizable(Fl_Widget &box)</a></h4> + +Adds a widget to the group and makes it the resizable widget. + +<h4><a name="Fl_Group.array">const Fl_Widget **Fl_Group::array() const</a></h4> + +Returns a pointer to the array of children. <i>This pointer can change +when children are added or removed!</i> + +<h4><a name="Fl_Group.begin">void Fl_Group::begin()</a></h4> + +<tt>begin()</tt> sets the current group so you can build the widget tree +by just constructing the widgets. <tt>begin()</tt> is automatically called by +the constructor for Fl_Group (and thus for Fl_Window as well). +<tt>begin()</tt> does <tt>current(this)</tt>. + +<p><i>Don't forget to <tt>end()</tt> the group or window!</i> + +<h4><a name="Fl_Group.child">Fl_Widget *Fl_Group::child(int n) const</a></h4> + +Returns child <tt>n</tt>, where <tt>0 <= n < children()</tt>. + +<h4><a name="Fl_Group.children">int Fl_Group::children() const</a></h4> + +Returns how many child widgets the group has. + +<h4><a name="Fl_Group.current">static Fl_Group *Fl_Group::current()<BR> +static void Fl_Group::current(Fl_Group *w)</a></h4> + +<tt>current()</tt> returns the currently active group in the widget tree. +To prevent widgets from being added to a group, call <tt>current()</tt> +with a <tt>NULL</tt> group. + +<h4><a name="Fl_Group.end">void Fl_Group::end()</a></h4> + +<tt>end()</tt> does <tt>current(this->parent())</tt>. Any new widgets added +to the widget tree will be added to the parent of the group. + +<h4><a name="Fl_Group.find">int Fl_Group::find(const Fl_Widget *w) const<BR> +int Fl_Group::find(const Fl_Widget &w) const</a></h4> + +Searches the child array for the widget and returns the index. Returns +<a href="#Fl_Group.children"><tt>children()</tt></a> if the widget is +<tt>NULL</tt> or not found. + +<h4><a name="Fl_Group.insert">void Fl_Group::insert(Fl_Widget &w, int n)<BR> +void Fl_Group::insert(Fl_Widget &w, Fl_Widget *beforethis)</a></h4> + +Inserts a widget into the child array. It is put at index <tt>n</tt> which +must be less or equal to children(). The second version does a +<tt>find(beforethis)</tt> and inserts using that index. + +<h4><a name="Fl_Group.remove">void Fl_Group::remove(Fl_Widget &w)</a></h4> + +Removes a widget from the group. This does nothing if the widget +is not currently a child of this group. + +<h4><a name="Fl_Group.resizeable">void Fl_Group::resizable(Fl_Widget *box)<BR> +void Fl_Group::resizable(Fl_Widget &box)<BR> +Fl_Widget *Fl_Group::resizable() const</a></h4> + +The resizable widget defines the resizing box for the group. When the +group is resized it calculates a new size and position for all of its +children. Widgets that are horizontally or vertically inside the dimensions +of the box are scaled to the new size. Widgets outside the box are moved. + +<p>In these examples the gray area is the resizable:<br> + +<p align=center><img SRC="resizebox1.gif" align=TOP height=240> +<img SRC="resizebox2.gif" align=TOP height=240> + +<p>The resizable may be set to the group itself (this is the default value +for an <tt>Fl_Group</tt>, although <tt>NULL</tt> is the default for an +<tt>Fl_Window</tt>), in which case all the contents are resized. If the +resizable is <tt>NULL</tt> then all widgets remain a fixed size and +distance from the top-left corner. + +<p>It is possible to achieve any type of resize behavior by using an +invisible <tt>Fl_Box</tt> as the resizable and/or by using a hierarchy of +child <tt>Fl_Group</tt>'s. + +</body> +</html> diff --git a/documentation/Fl_Hold_Browser.html b/documentation/Fl_Hold_Browser.html new file mode 100644 index 000000000..591d61a27 --- /dev/null +++ b/documentation/Fl_Hold_Browser.html @@ -0,0 +1,74 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Hold_Browser">class Fl_Hold_Browser</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Browser">Fl_Browser</a> + | + +----<b>Fl_Hold_Browser</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Hold_Browser.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Hold_Browser</tt> class is a subclass of <tt>Fl_Browser</tt> +which lets the user select a single item, or no items by clicking on +the empty space. As long as the mouse button is held down the item +pointed to by it is highlighted, and this highlighting remains on when +the mouse button is released. Normally the callback is done when the +user releases the mouse, but you can change this with <tt>when()</tt>. + +<p>See <a href="#Fl_Browser"><tt>Fl_Browser</tt></a> for methods to add +and remove lines from the browser. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Hold_Browser.Fl_Hold_Browser">Fl_Hold_Browser</a> + <li><a href="#Fl_Hold_Browser.~Fl_Hold_Browser">~Fl_Hold_Browser</a> + <li><a href="#Fl_Hold_Browser.deselect">deselect</a> + <li><a href="#Fl_Hold_Browser.select">select</a> + <li><a href="#Fl_Hold_Browser.value">value</a> +</ul> + +<h4><a name="Fl_Hold_Browser.Fl_Hold_Browser">Fl_Hold_Browser::Fl_Hold_Browser(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Hold_Browser</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_DOWN_BOX</tt>. + +<h4><a name="Fl_Hold_Browser.~Fl_Hold_Browser">virtual Fl_Hold_Browser::~Fl_Hold_Browser()</a></h4> + +The destructor <i>also deletes all the items in the list</i>. + +<h4><a name="Fl_Hold_Browser.deselect">int Fl_Browser::deselect()</a></h4> + +Same as <tt>value(0)</tt>. + +<h4><a name="Fl_Hold_Browser.select">int Fl_Browser::select(int,int=1)<br> +int Fl_Browser::selected(int) const</a></h4> + +You can use these for compatibility with +<a href="#Fl_Multi_Browser"><tt>Fl_Multi_Browser</tt></a>. If you +turn on the selection of more than one line the results are +unpredictable. + +<h4><a name="Fl_Hold_Browser.value">int Fl_Browser::value() const<br> +void Fl_Browser::value(int)</a></h4> + +Set or get which line is selected. This returns zero if no line is +selected, so be aware that this can happen in a callback. + +</body> +</html> diff --git a/documentation/Fl_Input.html b/documentation/Fl_Input.html new file mode 100644 index 000000000..89e10d235 --- /dev/null +++ b/documentation/Fl_Input.html @@ -0,0 +1,256 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Input">class Fl_Input</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Input_">Fl_Input_</a> + | + +----<b>Fl_Input</b> + | + +----<a href="#Fl_Float_Input">Fl_Float_Input</a>, <a href="#Fl_Int_Input">Fl_Int_Input</a>, + <a href="#Fl_Multiline_Input">Fl_Multiline_Input</a>, <a href="#Fl_Secret_Input">Fl_Secret_Input</a> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Input.H> +</pre></ul> + +<h3>Description</h3> + +This is the FLTK text input widget. It displays a single line of text +and lets the user edit it. Normally it is drawn with an inset box and +a white background. The text may contain any characters (even 0), and +will correctly display anything, using ^X notation for unprintable +control characters and \nnn notation for unprintable characters with +the high bit set. It assummes the font can draw any characters in the +ISO8859-1 character set. + +<table border=1> + +<tr><td><b>Mouse button 1</b></td> +<td>Moves the cursor to this point. Drag selects characters. Double +click selects words. Triple click selects all text. Shift+click +extends the selection.</td> + +<tr><td><b>Mouse button 2</b></td> +<td>Insert the current X selection at the cursor (unlike Motif this +does not move the insertion point to the mouse). If the widget does +not have the input focus (and thus no cursor) it puts the cursor where +clicked and inserts the selection there.</td> + +<tr><td><b>Mouse button 3</b></td> +<td>Currently acts like button 1.</td> + +<tr><td><b>Backspace</b></td> +<td>Deletes one character to the left, or deletes the +selected region.</td> + +<tr><td><b>Enter</b></td> +<td>May cause the callback, see when().</td> + +<tr><td><b>^A or Home</b></td> +<td>Go to start of line.</td> + +<tr><td><b>^B or Left</b></td> +<td>Move left</td> + +<tr><td><b>^C</b></td> +<td>Copy the selection to the clipboard</td> + +<tr><td><b>^D or Delete</b></td> +<td>Deletes one character to the right or deletes the selected region. +<i>Due to silly historical X problems, the Delete key will act like +Backspace until you type a "real" backspace.</i></td> + +<tr><td><b>^E or End</b></td> +<td>Go to the end of line.</td> + +<tr><td><b>^F or Right</b></td> +<td>Move right</td> + +<tr><td><b>^K</b></td> +<td>Delete to the end of line (next \n character) or deletes +a single \n character. These deletions are all concatenated into the +clipboard.</td> + +<tr><td><b>^N or Down</b></td> +<td>Move down (for Fl_Multiline_Input only, otherwise it moves to the +next input field).</td> + +<tr><td><b>^P or Up</b></td> +<td>Move up (for Fl_Multiline_Input only, otherwise it moves to the +previous input field).</td> + +<tr><td><b>^Q or<br>RightCtrl or<br>Compose</b></td> +<td>Start a <a href=compose.html>compose-character</a> sequence. The +next one or two keys typed define the character to insert. This also +can be used to "quote" control characters.</td> + +<tr><td><b>^U</b></td> +<td>Delete everything.</td> + +<tr><td><b>^V or ^Y</b></td> +<td>Paste the clipboard</td> + +<tr><td><b>^X or ^W</b></td> +<td>Copy the region to the clipboard and delete it.</td> + +<tr><td><b>^Z or ^_</b></td> +<td>Undo. This is a single-level undo mechanism, but all adjacent +deletions and insertions are concatenated into a single "undo". Often +this will undo a lot more than you expected.</td> + +<tr><td><b>Shift+move</b></td> +<td>Move the cursor but also extend the selection.</td> + +</table> + +<h3>Methods</h3> + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Input.Fl_Input">Fl_Input</a> + <li><a href="#Fl_Input.~Fl_Input">~Fl_Input</a> + <li><a href="#Fl_Input.cursor_color">cursor_color</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Input.index">index</a> + <li><a href="#Fl_Input.size">size</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Input.static_value">static_value</a> + <li><a href="#Fl_Input.textcolor">textcolor</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Input.textfont">textfont</a> + <li><a href="#Fl_Input.textsize">textsize</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Input.value">value</a> + <li><a href="#Fl_Input.when">when</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4><a name="Fl_Input.Fl_Input">Fl_Input::Fl_Input(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Input</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_DOWN_BOX</tt>. + +<h4><a name="Fl_Input.~Fl_Input">virtual Fl_Input::~Fl_Input()</a></h4> + +Destroys the widget and any value associated with it. + +<h4><a name="Fl_Input.value">const char *Fl_Input::value() const<br> +int Fl_Input::value(const char*)<br> +int Fl_Input::value(const char*, int)</a></h4> + +The first form returns the current value, which is a pointer to the +internal buffer and is valid only until the next event is +handled. + +<p>The second two forms change the text and set the mark and the point +to the end of it. The string is copied to the internal buffer. Passing +<tt>NULL</tt> is the same as "". This returns non-zero if the new +value is different than the current one. You can use the second +version to directly set the length if you know it already or want to +put nul's in the text. + +<h4><a name="Fl_Input.static_value">int Fl_Input::static_value(const char*)<br> +int Fl_Input::static_value(const char*, int)</a></h4> + +Change the text and set the mark and the point to the end of it. The +string is <i>not</i> copied. If the user edits the string it is copied +to the internal buffer then. This can save a great deal of time and +memory if your program is rapidly changing the values of text fields, +but this will only work if the passed string remains unchanged until +either the <tt>Fl_Input</tt> is destroyed or <tt>value()</tt> is called +again. + +<h4><a name="Fl_Input.size">int Fl_Input::size() const</a></h4> + +Returns the number of characters in <tt>value()</tt>. This may be greater than +<tt>strlen(value())</tt> if there are nul characters in it. + +<h4><a name="Fl_Input.index">char Fl_Input::index(int) const</a></h4> + +Same as <tt>value()[n]</tt>, but may be faster in plausible implementations. +No bounds checking is done. + +<h4><a name="Fl_Input.when">Fl_When Fl_Widget::when() const<br> +void Fl_Widget::when(Fl_When)</a></h4> + +Controls when callbacks are done. The following values are useful, +the default value is <tt>FL_WHEN_RELEASE</tt>: + +<ul> + <li><tt>0</tt>: The callback is not done, but <tt>changed()</tt> is + turned on. + + <li><tt>FL_WHEN_CHANGED</tt>: The callback is done each time the + text is changed by the user. + + <li><tt>FL_WHEN_RELEASE</tt>: The callback will + be done when this widget loses the focus, including when the window is + unmapped. This is a useful value for text fields in a panel where + doing the callback on every change is wasteful. However the callback + will also happen if the mouse is moved out of the window, which means + it should not do anything visible (like pop up an error message). You + might do better setting this to zero, and scanning all the items for + <tt>changed()</tt> when the OK button on a panel is pressed. + + <li><tt>FL_WHEN_ENTER_KEY</tt>: If the user types the Enter + key, the entire text is selected, and the callback is done if + the text has changed. Normally the Enter key will navigate to + the next field (or insert a newline for a + <tt>Fl_Mulitline_Input</tt>), this changes the behavior. + + <li><tt>FL_WHEN_ENTER_KEY|FL_WHEN_NOT_CHANGED</tt>: The Enter key + will do the callback even if the text has not changed. Useful for + command fields. +</ul> + +<h4><a name="Fl_Input.textcolor">Fl_Color Fl_Input::textcolor() const<br> +void Fl_Input::textcolor(Fl_Color)</a></h4> + +Gets or sets the color of the text in the input field. + +<h4><a name="Fl_Input.textfont">Fl_Font Fl_Input::textfont() const<br> +void Fl_Input::textfont(Fl_Font)</a></h4> + +Gets or sets the font of the text in the input field. + +<h4><a name="Fl_Input.textsize">uchar Fl_Input::textsize() const<br> +void Fl_Input::textsize(uchar)</a></h4> + +Gets or sets the size of the text in the input field. + +<h4><a name="Fl_Input.cursor_color">Fl_Color Fl_Input::cursor_color() const<br> +void Fl_Input::cursor_color(Fl_Color)</a></h4> + +Get or set the color of the cursor. This is black by default. + +</body> +</html> diff --git a/documentation/Fl_Input_.html b/documentation/Fl_Input_.html new file mode 100644 index 000000000..7dd9f6c63 --- /dev/null +++ b/documentation/Fl_Input_.html @@ -0,0 +1,220 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Input_">class Fl_Input_</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Input_</b> + | + +----<a href="#Fl_Input">Fl_Input</a> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Input_.H> +</pre></ul> + +<h3>Description</h3> + +This is a virtual base class below +<a href="#Fl_Input"><tt>Fl_Input</tt></a>. It has all the same interfaces, +but lacks the <tt>handle()</tt> and <tt>draw()</tt> method. You may +want to subclass it if you are one of those people who likes to change +how the editing keys work. + +<p>This can act like any of the subclasses of Fl_Input, by setting +<tt>type()</tt> to one of the following values: + +<ul><pre> +#define FL_NORMAL_INPUT 0 +#define FL_FLOAT_INPUT 1 +#define FL_INT_INPUT 2 +#define FL_MULTILINE_INPUT 4 +#define FL_SECRET_INPUT 5 +</pre></ul> + +<h3>Methods</h3> + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Input_.Fl_Input_">Fl_Input_</a> + <li><a href="#Fl_Input_.~Fl_Input_">~Fl_Input_</a> + <li><a href="#Fl_Input_.copy">copy</a> + <li><a href="#Fl_Input_.copy_cuts">copy_cuts</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Input_.cut">cut</a> + <li><a href="#Fl_Input_.drawtext">drawtext</a> + <li><a href="#Fl_Input_.handletext">handletext</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Input_.insert">insert</a> + <li><a href="#Fl_Input_.lineboundary">lineboundary</a> + <li><a href="#Fl_Input_.mark">mark</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Input_.maybe_do_callback">maybe_do_callback</a> + <li><a href="#Fl_Input_.position">position</a> + <li><a href="#Fl_Input_.replace">replace</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Input_.undo">undo</a> + <li><a href="#Fl_Input_.up_down_position">up_down_position</a> + <li><a href="#Fl_Input_.wordboundary">wordboundary</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4><a name="Fl_Input_.Fl_Input_">Fl_Input_::Fl_Input_(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Input_</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_DOWN_BOX</tt>. + +<h4><a name="Fl_Input_.~Fl_Input_">virtual Fl_Input_::~Fl_Input_()</a></h4> + +The destructor removes the widget and any value associated with it. + +<h4><a name="Fl_Input_.wordboundary">int Fl_Input_::wordboundary(int i) const</a></h4> + +Returns true if position <tt>i</tt> is at the start or end of a word. + +<h4><a name="Fl_Input_.lineboundary">int Fl_Input_::lineboundary(int i) const</a></h4> + +Returns true if position <tt>i</tt> is at the start or end of a line. + +<h4><a name="Fl_Input_.drawtext">void Fl_Input_::drawtext(int,int,int,int)</a></h4> + +Draw the text in the passed bounding box. If <tt>damage() & +FL_DAMAGE_ALL</tt> is true, this assummes the area has already been +erased to <tt>color()</tt>. Otherwise it does minimal update and +erases the area itself. + +<h4><a name="Fl_Input_.handletext">void Fl_Input_::handletext(int e,int,int,int,int)</a></h4> + +Default handler for all event types. Your <tt>handle()</tt> method +should call this for all events that it does not handle completely. +You must pass it the same bounding box as passed to <tt>draw()</tt>. +Handles <tt>FL_PUSH</tt>, <tt>FL_DRAG</tt>, <tt>FL_RELEASE</tt> to +select text, handles <tt>FL_FOCUS</tt> and <tt>FL_UNFOCUS</tt> to show +and hide the cursor. + +<h4><a name="Fl_Input_.up_down_position">int Fl_Input_::up_down_position(int i, int keepmark=0)</a></h4> + +Do the correct thing for arrow keys. Sets the position (and mark if +<i>keepmark</i> is zero) to somewhere in the same line as +<i>i</i>, such that pressing the arrows repeatedly will cause the +point to move up and down. + +<h4><a name="Fl_Input_.maybe_do_callback">void Fl_Input_::maybe_do_callback()</a></h4> + +Does the callback if <tt>changed()</tt> is true or if <tt>when() & +FL_WHEN_NOT_CHANGED</tt> is non-zero. You should call this at any +point you think you should generate a callback. + +<h4><a name="Fl_Input_.position">int Fl_Input_::position() const<br> +int Fl_Input_::position(int new_position, int new_mark)<br> +int Fl_Input_::position(int new_position_and_new_mark)</a></h4> + +The input widget maintains two pointers into the string. The "position" is +where the cursor is. The "mark" is the other end of the selected +text. If they are equal then there is no selection. Changing this +does not affect the clipboard (use <tt>copy()</tt> to do that). + +<p>Changing these values causes a <tt>redraw()</tt>. The new values +are bounds checked. The return value is non-zero if the new position +is different than the old one. <tt>position(n)</tt> is the same as +<tt>position(n,n)</tt>. <tt>mark(n)</tt> is the same as +<tt>position(position(),n)</tt>. + +<h4><a name="Fl_Input_.mark">int Fl_Input_::mark() const<br> +int Fl_Input_::mark(int new_mark)</a></h4> + +Gets or sets the current selection mark. <tt>mark(n)</tt> is the same +as <tt>position(position(),n)</tt>. + +<h4><a name="Fl_Input_.replace">int Fl_Input_::replace(int a, int b, const char *insert, int length=0)</a></h4> + +This call does all editing of the text. It deletes the region between +<tt>a</tt> and <tt>b</tt> (either one may be less or equal to the +other), and then inserts the string <tt>insert</tt> at that point and +leaves the <tt>mark()</tt> and <tt>position()</tt> after the +insertion. Does the callback if <tt>when() & FL_WHEN_CHANGED</tt> and +there is a change. + +<p>Set <tt>start</tt> and <tt>end</tt> equal to not delete anything. Set +<tt>insert</tt> to <tt>NULL</tt> to not insert anything. + +<p><tt>length</tt> must be zero or <tt>strlen(insert)</tt>, this saves +a tiny bit of time if you happen to already know the length of the +insertion, or can be used to insert a portion of a string or a string +containing nul's. + +<p><tt>a</tt> and <tt>b</tt> are clamped to the 0..<tt>size()</tt> +range, so it is safe to pass any values. + +<p><tt>cut()</tt> and <tt>insert()</tt> are just inline functions that +call <tt>replace()</tt>. + +<h4><a name="Fl_Input_.cut">int Fl_Input_::cut()<br> +int Fl_Input_::cut(int n)<br> +int Fl_Input_::cut(int a, int b);</a></h4> + +<tt>Fl_Input_::cut()</tt> deletes the current selection. +<tt>cut(n)</tt> deletes <tt>n</tt> characters after the +<tt>position()</tt>. <tt>cut(-n)</tt> deletes <tt>n</tt> characters +before the <tt>position()</tt>. <tt>cut(a,b)</tt> deletes the +characters between offsets <tt>a</tt> and <tt>b</tt>. <tt>A</tt>, +<tt>b</tt>, and <tt>n</tt> are all clamped to the size of the string. +The mark and point are left where the deleted text was. + +<p>If you want the data to go into the clipboard, do +<tt>Fl_Input_::copy()</tt> before calling <tt>Fl_Input_::cut()</tt>, or +do <tt>Fl_Input_::copy_cuts()</tt> afterwards. + +<h4><a name="Fl_Input_.insert">int Fl_Input_::insert(const char *t,int l=0)</a></h4> + +Insert the string <tt>t</tt> at the current position, and leave the +mark and position after it. If <tt>l</tt> is not zero then it is +assummed to be <tt>strlen(t)</tt>. + +<h4><a name="Fl_Input_.copy">int Fl_Input_::copy()</a></h4> + +Put the current selection between <tt>mark()</tt> and +<tt>position()</tt> into the clipboard. Does not replace the old +clipboard contents if <tt>position()</tt> and <tt>mark()</tt> are +equal. + +<h4><a name="Fl_Input_.undo">int Fl_Input_::undo()</a></h4> + +Does undo of several previous calls to <tt>replace()</tt>. Returns +non-zero if any change was made. + +<h4><a name="Fl_Input_.copy_cuts">int Fl_Input_::copy_cuts()</a></h4> + +Copy all the previous contiguous cuts from the undo information to the +clipboard. This is used to make ^K work. + +</body> +</html> diff --git a/documentation/Fl_Int_Input.html b/documentation/Fl_Int_Input.html new file mode 100644 index 000000000..e76cc43ef --- /dev/null +++ b/documentation/Fl_Int_Input.html @@ -0,0 +1,47 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Int_Input">class Fl_Int_Input</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Input">Fl_Input</a> + | + +----<b>Fl_Int_Input</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Input.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Int_Input</tt> class is a subclass of <tt>Fl_Input</tt> that +displays its input in red when the value string is not a legal integer +value. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Int_Input.Fl_Int_Input">Fl_Int_Input</a> + <li><a href="#Fl_Int_Input.~Fl_Int_Input">~Fl_Int_Input</a> +</ul> + +<h4><a name="Fl_Int_Input.Fl_Int_Input">Fl_Int_Input::Fl_Int_Input(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Int_Input</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_DOWN_BOX</tt>. + +<h4><a name="Fl_Int_Input.~Fl_Int_Input">virtual Fl_Int_Input::~Fl_Int_Input()</a></h4> + +Destroys the widget and any value associated with it. + +</body> +</html> diff --git a/documentation/Fl_Light_Button.html b/documentation/Fl_Light_Button.html new file mode 100644 index 000000000..d60af5c97 --- /dev/null +++ b/documentation/Fl_Light_Button.html @@ -0,0 +1,53 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Light_Button">class Fl_Light_Button</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Button">Fl_Button</a> + | + +----<b>Fl_Light_Button</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Light_Button.H> +</pre></ul> + +<h3>Description</h3> + +Buttons generate callbacks when they are clicked by the user. You +control exactly when and how by changing the values for <tt>type()</tt> and +<tt>when()</tt>. + +<P>The <tt>Fl_Light_Button</tt> subclass display the "on" state by +turning on a light, rather than drawing pushed in. The shape of the +"light" is initially set to FL_DOWN_BOX. The color of the +light when on is controlled with <tt>selection_color()<tt>, which defaults to +FL_YELLOW. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Light_Button.Fl_Light_Button">Fl_Light_Button</a> + <li><a href="#Fl_Light_Button.~Fl_Light_Button">~Fl_Light_Button</a> +</ul> + +<h4><a name="Fl_Light_Button.Fl_Light_Button">Fl_Light_Button::Fl_Light_Button(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Light_Button</tt> widget using the given position, +size, and label string. + +<h4><a name="Fl_Light_Button.~Fl_Light_Button">Fl_Light_Button::~Fl_Light_Button()</a></h4> + +The destructor deletes the check button. + +</body> +</html> diff --git a/documentation/Fl_Menu_.html b/documentation/Fl_Menu_.html new file mode 100644 index 000000000..f35816496 --- /dev/null +++ b/documentation/Fl_Menu_.html @@ -0,0 +1,220 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Menu_">class Fl_Menu_</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Menu_</b>----<a href="#Fl_Menu_Item">Fl_Menu_Item</a> + | + +----<a href="#Fl_Choice">Fl_Choice</a>, <a href="#Fl_Menu_Bar">Fl_Menu_Bar</a>, <a href="#Fl_Menu_Button">Fl_Menu_Button</a> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Menu_.H> +</pre></ul> + +<h3>Description</h3> + +All widgets that have a menu in FLTK are subclassed off of this class. +Currently FLTK provides you with +<a href="#Fl_Menu_Button"><tt>Fl_Menu_Button</tt></a>, +<a href="#Fl_Menu_Bar"><tt>Fl_Menu_Bar</tt></a>, and +<a href="#Fl_Choice"><tt>Fl_Choice</tt></a>. + +<p>The class contains a pointer to an array of structures of type +<a href="#Fl_Menu_Item"><tt>Fl_Menu_Item</tt></a>. +These describe the contents of the menu. Usually the array is a large +initialization constant, but there are methods to build it +dynamically. + +<h3>Methods</h3> + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Menu_.Fl_Menu_">Fl_Menu_</a> + <li><a href="#Fl_Menu_.~Fl_Menu_">~Fl_Menu_</a> + <li><a href="#Fl_Menu_.add">add</a> + <li><a href="#Fl_Menu_.clear">clear</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Menu_.down_box">down_box</a> + <li><a href="#Fl_Menu_.global">global</a> + <li><a href="#Fl_Menu_.menu">menu</a> + <li><a href="#Fl_Menu_.mode">mode</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Menu_.remove">remove</a> + <li><a href="#Fl_Menu_.replace">replace</a> + <li><a href="#Fl_Menu_.shortcut">shortcut</a> + <li><a href="#Fl_Menu_.size">size</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Menu_.test_shortcut">test_shortcut</a> + <li><a href="#Fl_Menu_.text">text</a> + <li><a href="#Fl_Menu_.textcolor">textcolor</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Menu_.textfont">textfont</a> + <li><a href="#Fl_Menu_.textsize">textsize</a> + <li><a href="#Fl_Menu_.value">value</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4><a name="Fl_Menu_.Fl_Menu_">Fl_Menu_::Fl_Menu_(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Menu_</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_NO_BOX</tt>. + +<h4><a name="Fl_Menu_.~Fl_Menu_">virtual Fl_Menu_::~Fl_Menu_()</a></h4> + +Destroys the menu and its items. + +<h4><a name="Fl_Menu_.menu">const Fl_Menu_Item* Fl_Menu_::menu() const<br> +void Fl_Menu_::menu(const Fl_Menu_Item*)</a></h4> + +Get or set the menu array directly. Setting it to <tt>NULL</tt> indicates that +you want the widget to allocate its own array. + +<h4><a name="Fl_Menu_.value">int Fl_Menu_::value() const<br> +int Fl_Menu_::value(int)<br> +int Fl_Menu_::value(const Fl_Menu_Item*)</a></h4> + +The value is the index into <tt>menu()</tt> of the last item chosen by the +user. It is zero initially. You can set it as an integer, or set it +with a pointer to a menu item. The set routines return non-zero if +the new value is different than the old one. + +<h4><a name="Fl_Menu_.test_shortcut">const Fl_Menu_Item* Fl_Menu_::test_shortcut()</a></h4> + +Only call this in response to <tt>FL_SHORTCUT events</tt>. If the event +matches an entry in the menu that entry is selected and the callback +will be done (or <tt>changed()</tt> will be set). This allows shortcuts +directed at one window to call menus in another. + +<h4><a name="Fl_Menu_.global">void Fl_Menu_::global()</a></h4> + +Make the shortcuts for this menu work no matter what window has the +focus when you type it. This is done by using <a +href="#add_handler"><tt>Fl::add_handler()</tt></a>. This +<tt>Fl_Menu_</tt> widget does not have to be visible (ie the window it +is in can be hidden, or it does not have to be put in a window at all). + +<p>Currently there can be only one <tt>global()<tt> menu. Setting a new one +will replace the old one. There is no way to remove the <tt>global()</tt> +setting (including destroying the menu). + +<h4><a name="Fl_Menu_.text">const char* Fl_Menu_::text() const<br> +const char* Fl_Menu_::text(int i) const</a></h4> + +Returns the title of the last item chosen, or of item <tt>i</tt>. + +<h4><a name="Fl_Menu_.size">int Fl_Menu_::size() const</a></h4> + +This returns <tt>menu()->size()</tt>, which is how many entries are in +the array, not counting the <tt>NULL</tt> ending, but including all +submenus titles and the <tt>NULL</tt>'s that end them. If the menu is +<tt>NULL</tt> this returns zero. + +<h4><a name="Fl_Menu_.add">int Fl_Menu_::add(const char *,const char *,Fl_Callback *,void *v=0,int f=0)<br> +int Fl_Menu_::add(const char *)</a></h4> + +The first form adds a new menu item, with a <tt>title</tt> string, +<tt>shortcut</tt> string, <tt>callback</tt>, argument to the callback, +and flags. If <tt>menu()</tt> was originally set with <tt>NULL</tt> +then space is allocated for the new item. If instead you gave it an +array then the array must have enough empty space for the new item. +The title string is copied, but the shortcut is not. + +<p>The second form splits the string at any | characters and then does +<tt>add(s,0,0,0,0)</tt> with each section. This is often useful if you +are just using the value, and is compatable with some Forms programs. + +<p>Text is a string of the form "foo/bar/baz", this example will result +in a submenu called "foo" and one in that called "bar" and and entry +called "baz". The text is copied to new memory and can be freed. The +other arguments are copied into the menu item unchanged. + +<P>If an item exists already with that name then it is replaced with +this new one. Otherwise this new one is added to the end of the +correct menu or submenu. The return value is the offset into the +array that the new entry was placed at. + +<p>No bounds checking is done, the table must be big enough for all the +entries you plan to add. Don't forget that there is a <tt>NULL</tt> terminator +on the end, and the first time a item is added to a submenu three +items are added (the title and the <tt>NULL</tt> terminator, as well as the +actual menu item) + +<P>The return value is the index into the array that the entry was put. + +<h4><a name="Fl_Menu_.clear">void Fl_Menu_::clear()</a></h4> + +Delete all the menu items. Don't do this if you used <tt>menu(x)</tt> to +set it to your own array. You should do this before destroying the +<tt>Fl_Menu_</tt> widget if it uses it's own array. + +<h4><a name="Fl_Menu_.replace">void Fl_Menu_::replace(int n, const char *)</a></h4> + +Changes the text of item <tt>n</tt>. The passed string is copied. + +<h4><a name="Fl_Menu_.remove">void Fl_Menu_::remove(int n)</a></h4> + +Deletes item <tt>n</tt> from the menu. + +<h4><a name="Fl_Menu_.shortcut">void Fl_Menu_::shortcut(int i, int n);</a></h4> + +Changes the shortcut of item <tt>i</tt> to <tt>n</tt>. + +<h4><a name="Fl_Menu_.mode">void Fl_Menu_::mode(int i,int x);</a></h4> + +Changes the flags of item <tt>i</tt>. + +<h4><a name="Fl_Menu_.textcolor">Fl_Color Fl_Menu_::textcolor() const<br> +void Fl_Menu_::textcolor(Fl_Color)</a></h4> + +Get or set the current color of menu item labels. + +<h4><a name="Fl_Menu_.textfont">Fl_Font Fl_Menu_::textfont() const<br> +void Fl_Menu_::textfont(Fl_Font)</a></h4> + +Get or set the current font of menu item labels. + +<h4><a name="Fl_Menu_.textsize">uchar Fl_Menu_::textsize() const<br> +void Fl_Menu_::textsize(uchar)</a></h4> + +Get or set the font size of menu item labels. + +<h4><a name="Fl_Menu_.down_box">Fl_Boxtype Fl_Menu_::down_box() const<br> +void Fl_Menu_::down_box(Fl_Boxtype)</a></h4> + +This box type is used to surround the currently-selected items in the +menus. If this is <tt>FL_NO_BOX</tt> then it acts like +<tt>FL_THIN_UP_BOX</tt> and <tt>selection_color()</tt> acts like +<tt>FL_WHITE</tt>, for back compatability. + +</body> +</html> diff --git a/documentation/Fl_Menu_Bar.html b/documentation/Fl_Menu_Bar.html new file mode 100644 index 000000000..d8ff312cf --- /dev/null +++ b/documentation/Fl_Menu_Bar.html @@ -0,0 +1,85 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Menu_Bar">class Fl_Menu_Bar</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Menu_">Fl_Menu_</a> + | + +----<b>Fl_Menu_Bar</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Menu_Bar.H> +</pre></ul> + +<h3>Description</h3> + +This widget provides a standard menubar interface. Usually you will +put this widget along the top edge of your window. The height of the +widget should be 30 for the menu titles to draw correctly with the default +font. + +<p>The items on the bar and the menus they bring up are defined by a +single <a href="#Fl_Menu_Item"><tt>Fl_Menu_Item</tt></a> array. Because a +<tt>Fl_Menu_Item</tt> array defines a hierarchy, the top level menu defines the +items in the menubar, while the submenus define the pull-down menus. +Sub-sub menus and lower pop up to the right of the submenus. + +<p><img src=menubar.gif> + +<P>If there is an item in the top menu that is not a title of a +submenu, then it acts like a "button" in the menubar. Clicking on +it will pick it. + +<P>When the user picks an item off the menu, the item's callback is +done with the menubar as the <tt>Fl_Widget*</tt> argument. If the item +does not have a callback the menubar's callback is done instead. + +<p>Submenus will also pop up in response to shortcuts indicated by +putting a '&' character in the name field of the menu item. If you +put a '&' character in a top-level "button" then the shortcut picks +it. The '&' character in submenus is ignored until the menu is popped +up. + +<p>Typing the <tt>shortcut()</tt> of any of the menu items will cause callbacks +exactly the same as when you pick the item with the mouse. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Menu_Bar.Fl_Menu_Bar">Fl_Menu_Bar</a> + <li><a href="#Fl_Menu_Bar.~Fl_Menu_Bar">~Fl_Menu_Bar</a> +</ul> + +<h4><a name="Fl_Menu_Bar.Fl_Menu_Bar">Fl_Menu_Bar::Fl_Menu_Bar(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Menu_Bar</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_UP_BOX</tt>. + +<p>The constructor sets <tt>menu()</tt> to <tt>NULL</tt>. See <a +href="#Fl_Menu_"><tt>Fl_Menu_</tt></a> for the methods to set or change +the menu. + +<P><tt>labelsize()</tt>, <tt>labelfont()</tt>, and +<tt>labelcolor()</tt> are used to control how the menubar items are +drawn. They are initialized from the <tt>Fl_Menu</tt> static +variables, but you can change them if desired. + +<p><tt>label()</tt> is ignored unless you change <tt>align()</tt> to +put it outside the menubar. + +<h4><a name="Fl_Menu_Bar.~Fl_Menu_Bar">virtual Fl_Menu_Bar::~Fl_Menu_Bar()</a></h4> + +The destructor removes the <tt>Fl_Menu_Bar</tt> widget and all of its menu items. + +</body> +</html> diff --git a/documentation/Fl_Menu_Button.html b/documentation/Fl_Menu_Button.html new file mode 100644 index 000000000..43bd2d6a6 --- /dev/null +++ b/documentation/Fl_Menu_Button.html @@ -0,0 +1,101 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Menu_Button">class Fl_Menu_Button</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Menu_">Fl_Menu_</a> + | + +----<b>Fl_Menu_Button</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Menu_Button.H> +</pre></ul> + +<h3>Description</h3> + +This is a button that when pushed pops up a menu (or hierarchy of +menus) defined by an array of <a href="#Fl_Menu_Item"><tt>Fl_Menu_Item</tt></a> +objects. + +<P><img src=menu_button.gif> + +<p>Normally any mouse button will pop up a menu and it is lined up +below the button as shown in the picture. However an <tt>Fl_Menu_Button</tt> +may also control a pop-up menu. This is done by setting the +<tt>type()</tt>, +see below. + +<p>The menu will also pop up in response to shortcuts indicated by +putting a '&' character in the <tt>label()</tt>. + +<p>Typing the <tt>shortcut()</tt> of any of the menu items will cause +callbacks exactly the same as when you pick the item with the mouse. +The '&' character in menu item names are only looked at when the menu +is popped up, however. + +<P>When the user picks an item off the menu, the item's callback is +done with the menu_button as the <tt>Fl_Widget*</tt> argument. If the item +does not have a callback the menu_button's callback is done instead. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Menu_Button.Fl_Menu_Button">Fl_Menu_Button</a> + <li><a href="#Fl_Menu_Button.~Fl_Menu_Button">~Fl_Menu_Button</a> + <li><a href="#Fl_Menu_Button.popup">popup</a> + <li><a href="#Fl_Menu_Button.type">type</a> +</ul> + +<h4><a name="Fl_Menu_Button.Fl_Menu_Button">Fl_Menu_Button::Fl_Menu_Button(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Menu_Button</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_UP_BOX</tt>. + +<p>The constructor sets <tt>menu()</tt> to <tt>NULL</tt>. See <a +href="#Fl_Menu_"><tt>Fl_Menu_</tt></a> for the methods to set or change +the menu. + +<h4><a name="Fl_Menu_Button.~Fl_Menu_Button">virtual Fl_Menu_Button::~Fl_Menu_Button()</a></h4> + +The destructor removes the <tt>Fl_Menu_Button</tt> widget and all of its menu items. + +<h4><a name="Fl_Menu_Button.popup">const Fl_Menu* Fl_Menu_Button::popup()</a></h4> + +Act exactly as though the user clicked the button or typed the shortcut +key. The menu appears, it waits for the user to pick an item, and if +they pick one it sets <tt>value()</tt> and does the callback or sets +<tt>changed()</tt> as described above. The menu item is returned or +<tt>NULL<tt> if the user dismisses the menu. + +<h4><a name="Fl_Menu_Button.type">void Fl_Widget::type(uchar)</a></h4> + +If <tt>type()</tt> is zero a normal menu button is produced. If it is +nonzero then this is a pop-up menu. The bits in <tt>type()</tt> +indicate what mouse buttons pop up the menu. For convienece the +constants <tt>Fl_Menu_Button::POPUP1, POPUP2, POPUP3, POPUP12, POPUP13, +POPUP23</tt>, and <tt>POPUP123</tt> are defined. +<tt>Fl_Menu_Button::POPUP3</tt> is usually what you want. + +<p>A popup menu button is invisible and does not interfere with any +events other than the mouse button specified (and any shortcuts). The +widget can be stretched to cover all your other widgets by putting it last +in the hierarchy so it is "on top". You can also make several widgets +covering different areas for context-sensitive popup menus. + +<p>The popup menus appear with the cursor pointing at the previously +selected item. This is a <i>feature</i>. If you don't like it, do +<tt>value(0)</tt> after the menu items are picked to forget the current +item. + +</body> +</html> diff --git a/documentation/Fl_Menu_Item.html b/documentation/Fl_Menu_Item.html new file mode 100644 index 000000000..4dc738c26 --- /dev/null +++ b/documentation/Fl_Menu_Item.html @@ -0,0 +1,366 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Menu_Item">struct Fl_Menu_Item</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Menu_Item</b>----<a href="#Fl_Menu_">Fl_Menu_</a> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Menu_Item.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Menu_Item</tt> structure defines a single menu item that is +used by the <tt>Fl_Menu_</tt> class. This structure is defined in +<tt><FL/Fl_Menu_Item.H></tt> + +<ul><pre> +struct Fl_Menu_Item { + const char* text; // label() + ulong shortcut_; + Fl_Callback* callback_; + void* user_data_; + int flags; + uchar labeltype_; + uchar labelfont_; + uchar labelsize_; + uchar labelcolor_; +}; + +enum { // values for flags: + FL_MENU_INACTIVE = 1, + FL_MENU_TOGGLE = 2, + FL_MENU_VALUE = 4, + FL_MENU_RADIO = 8, + FL_MENU_INVISIBLE = 0x10, + FL_SUBMENU_POINTER = 0x20, + FL_SUBMENU = 0x40, + FL_MENU_DIVIDER = 0x80, + FL_MENU_HORIZONTAL = 0x100 +}; +</pre></ul> + +Typically menu items are statically defined; for example: + +<table> +<tr valign=top> + <td><img align=left src=menu.gif></td> + <td><pre> +Fl_Menu_Item popup[] = { + {"&alpha", FL_ALT+'a', the_cb, (void*)1}, + {"&beta", FL_ALT+'b', the_cb, (void*)2}, + {"gamma", FL_ALT+'c', the_cb, (void*)3, FL_MENU_DIVIDER}, + {"&strange", 0, strange_cb}, + {"&charm", 0, charm_cb}, + {"&truth", 0, truth_cb}, + {"b&eauty", 0, beauty_cb}, + {"sub&menu", 0, 0, 0, FL_SUBMENU}, + {"one"}, + {"two"}, + {"three"}, + {0}, + {"inactive", FL_ALT+'i', 0, 0, FL_MENU_INACTIVE|FL_MENU_DIVIDER}, + {"invisible",FL_ALT+'i', 0, 0, FL_MENU_INVISIBLE}, + {"check", FL_ALT+'i', 0, 0, FL_MENU_TOGGLE|FL_MENU_VALUE}, + {"box", FL_ALT+'i', 0, 0, FL_MENU_TOGGLE}, +{0}}; + </pre></td> +</tr> +</table> + +A submenu title is identified by the bit <tt>FL_SUBMENU</tt> in the +<tt>flags</tt> field, and ends with a <tt>label()</tt> that is +<tt>NULL</tt>. You can nest menus to any depth. A pointer to the +first item in the submenu can be treated as an <tt>Fl_Menu</tt> array +itself. It is also possible to make seperate submenu arrays with +<tt>FL_SUBMENU_POINTER</tt> flags. + +<p>You should use the method functions to access structure members and +not access them directly to avoid compatibility problems with future +releases of FLTK. + +<h3>Methods</h3> + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Menu_Item.label">label</a> + <li><a href="#Fl_Menu_Item.labeltype">labeltype</a> + <li><a href="#Fl_Menu_Item.labelcolor">labelcolor</a> + <li><a href="#Fl_Menu_Item.labelfont">labelfont</a> + <li><a href="#Fl_Menu_Item.labelsize">labelsize</a> + <li><a href="#Fl_Menu_Item.callback">callback</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Menu_Item.user_data">user_data</a> + <li><a href="#Fl_Menu_Item.argument">argument</a> + <li><a href="#Fl_Menu_Item.do_callback">do_callback</a> + <li><a href="#Fl_Menu_Item.shortcut">shortcut</a> + <li><a href="#Fl_Menu_Item.submenu">submenu</a> + <li><a href="#Fl_Menu_Item.checkbox">checkbox</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Menu_Item.radio">radio</a> + <li><a href="#Fl_Menu_Item.value">value</a> + <li><a href="#Fl_Menu_Item.set">set</a> + <li><a href="#Fl_Menu_Item.setonly">setonly</a> + <li><a href="#Fl_Menu_Item.clear">clear</a> + <li><a href="#Fl_Menu_Item.visible">visible</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Menu_Item.show">show</a> + <li><a href="#Fl_Menu_Item.hide">hide</a> + <li><a href="#Fl_Menu_Item.active">active</a> + <li><a href="#Fl_Menu_Item.activate">activate</a> + <li><a href="#Fl_Menu_Item.deactivate">deactivate</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Menu_Item.popup">popup</a> + <li><a href="#Fl_Menu_Item.pulldown">pulldown</a> + <li><a href="#Fl_Menu_Item.test_shortcut">test_shortcut</a> + <li><a href="#Fl_Menu_Item.size">size</a> + <li><a href="#Fl_Menu_Item.next">next</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4><a name="Fl_Menu_Item.label">const char* Fl_Menu_Item::label() const<br> +void Fl_Menu_Item::label(const char*)<br> +void Fl_Menu_Item::label(Fl_Labeltype, const char*)</a></h4> + +This is the title of the item. A <tt>NULL</tt> here indicates the end of the +menu (or of a submenu). A '&' in the item will print an underscore +under the next letter, and if the menu is popped up that letter will +be a "shortcut" to pick that item. To get a real '&' put two in a +row. + +<h4><a name="Fl_Menu_Item.labeltype">Fl_Labeltype Fl_Menu_Item::labeltype() const<br> +void Fl_Menu_Item::labeltype(Fl_Labeltype)</a></h4> + +A <tt>labeltype</tt> identifies a routine that draws the label of the +widget. This can be used for special effects such as emboss, or to use +the <tt>label()</tt> pointer as another form of data such as a bitmap. +The value <tt>FL_NORMAL_LABEL</tt> prints the label as text. + +<h4><a name="Fl_Menu_Item.labelcolor">Fl_Color Fl_Menu_Item::labelcolor() const<br> +void Fl_Menu_Item::labelcolor(Fl_Color)</a></h4> + +This color is passed to the labeltype routine, and is typically the +color of the label text. This defaults to <tt>FL_BLACK</tt>. If this +color is not black fltk will <i>not</i> use overlay bitplanes to draw +the menu - this is so that images put in the menu draw correctly. + +<h4><a name="Fl_Menu_Item.labelfont">Fl_Font Fl_Menu_Item::labelfont() const<br> +void Fl_Menu_Item::labelfont(Fl_Font)</a></h4> + +Fonts are identified by small 8-bit indexes into a table. See the <a +href="#Enumerations">enumeration list</a> for predefined fonts. The +default value is a Helvetica font. The function <a +href="#set_font"><tt>Fl::set_font()</tt></a> can define new fonts. + +<h4><a name="Fl_Menu_Item.labelsize">uchar Fl_Menu_Item::labelsize() const<br> +void Fl_Menu_Item::labelsize(uchar)</a></h4> + +Gets or sets the label font pixel size/height. + +<h4><a name="Fl_Menu_Item.callback">typedef void (Fl_Callback)(Fl_Widget*, void*)<br> +Fl_Callback* Fl_Menu_Item::callback() const<br> +void Fl_Menu_Item::callback(Fl_Callback*, void* = 0)<br> +void Fl_Menu_Item::callback(void (*)(Fl_Widget*))</a></h4> + +Each item has space for a callback function and an argument for that +function. Due to back compatability, the <tt>Fl_Menu_Item</tt> itself +is not passed to the callback, instead you have to get it by calling +<tt>((Fl_Menu_*)w)->mvalue()</tt> where <tt>w</tt> is the widget +argument. + +<h4><a name="Fl_Menu_Item.user_data">void* Fl_Menu_Item::user_data() const<br> +void Fl_Menu_Item::user_data(void*)</a></h4> + +Get or set the <tt>user_data</tt> argument that is sent to the callback +function. + +<h4><a name="Fl_Menu_Item.argument">void Fl_Menu_Item::callback(void (*)(Fl_Widget*, long), long = 0)<br> +long Fl_Menu_Item::argument() const<br> +void Fl_Menu_Item::argument(long)</a></h4> + +For convenience you can also define the callback as taking a +<tt>long</tt> argument. This is implemented by casting this to a +<tt>Fl_Callback</tt> and casting the <tt>long</tt> to a <tt>void*</tt> +and may not be portable to some machines. + +<h4><a name="Fl_Menu_Item.do_callback">void Fl_Menu_Item::do_callback(Fl_Widget*)<br> +void Fl_Menu_Item::do_callback(Fl_Widget*, void*)<br> +void Fl_Menu_Item::do_callback(Fl_Widget*, long)</a></h4> + +Call the <tt>Fl_Menu_Item</tt> item's callback, and provide the +<tt>Fl_Widget</tt> argument (and optionally override the user_data() +argument). You must first check that <tt>callback()</tt> is non-zero before +calling this. + +<h4><a name="Fl_Menu_Item.shortcut">ulong Fl_Menu_Item::shortcut() const<br> +void Fl_Menu_Item::shortcut(ulong)</a></h4> + +Sets exactly what key combination will trigger the menu item. The +value is a logical 'or' of a key and a set of shift flags, for +instance <tt>FL_ALT+'a'</tt> or <tt>FL_ALT+FL_F+10</tt> or +just 'a'. A value of zero disables the shortcut. + +<p>The key can be any value returned by <a +href="#event_key"><tt>Fl::event_key()</tt></a>, but will usually be an +ASCII letter. Use a lower-case letter unless you require the shift key +to be held down. + +<p>The shift flags can be any set of values accepted by <a +href="#event_state"><tt>Fl::event_state()</tt></a>. If the bit is on +that shift key must be pushed. Meta, Alt, Ctrl, and Shift must be off +if they are not in the shift flags (zero for the other bits indicates +a "don't care" setting). + +<h4><a name="Fl_Menu_Item.submenu">int Fl_Menu_Item::submenu() const</a></h4> + +Returns true if either <tt>FL_SUBMENU</tt> or +<tt>FL_SUBMENU_POINTER</tt> is on in the flags. <tt>FL_SUBMENU</tt> +indicates an embedded submenu that goes from the next item through the +next one with a <tt>NULL</tt> <tt>label()</tt>. +<tt>FL_SUBMENU_POINTER</tt> indicates that <tt>user_data()</tt> is a +pointer to another menu array. + +<h4><a name="Fl_Menu_Item.checkbox">int Fl_Menu_Item::checkbox() const</a></h4> + +Returns true if a checkbox will be drawn next to this item. This is +true if <tt>FL_MENU_TOGGLE</tt> or <tt>FL_MENU_RADIO</tt> is set in the flags. + +<h4><a name="Fl_Menu_Item.radio">int Fl_Menu_Item::radio() const</a></h4> + +Returns true if this item is a radio item. When a radio button is +selected all "adjacent" radio buttons are turned off. A set of radio +items is delimited by an item that has <tt>radio()</tt> false, or by an item +with <tt>FL_MENU_DIVIDER</tt> turned on. + +<h4><a name="Fl_Menu_Item.value">int Fl_Menu_Item::value() const</a></h4> + +Returns the current value of the check or radio item. + +<h4><a name="Fl_Menu_Item.set">void Fl_Menu_Item::set()</a></h4> + +Turns the check or radio item "on" for the menu item. Note that this does not +turn off any adjacent radio items like <tt>set_only()</tt> does. + +<h4><a name="Fl_Menu_Item.setonly">void Fl_Menu_Item::setonly()</a></h4> + +Turns the radio item "on" for the menu item and turns off adjacent radio +item. + +<h4><a name="Fl_Menu_Item.clear">void Fl_Menu_Item::clear()</a></h4> + +Turns the check or radio item "off" for the menu item. + +<h4><a name="Fl_Menu_Item.visible">int Fl_Menu_Item::visible() const</a></h4> + +Gets the visibility of an item. + +<h4><a name="Fl_Menu_Item.show">void Fl_Menu_Item::show()</a></h4> + +Makes an item visible in the menu. + +<h4><a name="Fl_Menu_Item.hide">void Fl_Menu_Item::hide()</a></h4> + +Hides an item in the menu. + +<h4><a name="Fl_Menu_Item.active">int Fl_Menu_Item::active() const</a></h4> + +Get whether or not the item can be picked. + +<h4><a name="Fl_Menu_Item.activate">void Fl_Menu_Item::activate()</a></h4> + +Allows a menu item to be picked. + +<h4><a name="Fl_Menu_Item.deactivate">void Fl_Menu_Item::deactivate()</a></h4> + +Prevents a menu item from being picked. Note that this will also cause the +menu item to appear grayed-out. + +<h4><a name="Fl_Menu_Item.popup">const Fl_Menu_Item *Fl_Menu_Item::popup(int X, int Y, const char* title = 0, const Fl_Menu_Item* picked = 0, const Fl_Menu_* button = 0) const</a></h4> + +This method is called by widgets that want to display menus. The menu +stays up until the user picks an item or dismisses it. The selected +item (or <tt>NULL</tt> if none) is returned. <i>This does not do the +callbacks or change the state of check or radio items.</i> + +<p><tt>X,Y</tt> is the position of the mouse cursor, relative to the +window that got the most recent event (usually you can pass +<tt>Fl::event_x()</tt> and <tt>Fl::event_y()</tt> unchanged here). + +<p><tt>title</tt> is a character string title for the menu. If non-zero +a small box appears above the menu with the title in it. + +<p>The menu is positioned so the cursor is centered over the item +<tt>picked</tt>. This will work even if <tt>picked</tt> is in a submenu. +If <tt>picked</tt> is zero or not in the menu item table the menu is +positioned with the cursor in the top-left corner. + +<p><tt>button</tt> is a pointer to an <a href="#Fl_Menu_"><tt>Fl_Menu_</tt></a> +from which the color and boxtypes for the menu are pulled. If <tt>NULL</tt> +then defaults are used. + +<h4><a name="Fl_Menu_Item.pulldown">const Fl_Menu_Item *Fl_Menu_Item::pulldown(int X, int Y, int W, int H, const Fl_Menu_Item* picked = 0, const Fl_Menu_* button = 0, const Fl_Menu_Item* title = 0, int menubar=0) const</a></h4> + +<tt>pulldown()</tt> is similar to <tt>popup()</tt>, but a rectangle is +provided to position the menu. The menu is made at least <tt>W</tt> +wide, and the <tt>picked</tt> item is centered over the rectangle (like +<tt>Fl_Choice</tt> uses). If <tt>picked</tt> is zero or not found, the +menu is aligned just below the rectangle (like a pulldown menu). + +<p>The <tt>title</tt> and <tt>menubar</tt> arguments are used internally by +the <tt>Fl_Menu_</tt> widget. + +<h4><a name="Fl_Menu_Item.test_shortcut">const Fl_Menu_Item* Fl_Menu_Item::test_shortcut() const</a></h4> + +This is designed to be called by a widgets <tt>handle()</tt> method in +response to a <tt>FL_SHORTCUT</tt> event. If the current event matches +one of the items shortcut, that item is returned. If the keystroke +does not match any shortcuts then <tt>NULL</tt> is returned. This only +matches the <tt>shortcut()</tt> fields, not the letters in the title +preceeded by '&'. + +<h4><a name="Fl_Menu_Item.size">int Fl_Menu_Item::size()</a></h4> + +Return the offset of the <tt>NULL</tt> terminator that ends this menu, +correctly skipping over submenus. To copy a menu you should copy +<tt>size() + 1</tt> structures. + +<h4><a name="Fl_Menu_Item.next">const Fl_Menu_Item* Fl_Menu_Item::next(int n=1) const<br> +Fl_Menu_Item* Fl_Menu_Item::next(int n=1);</a></h4> + +Advance a pointer by <tt>n</tt> items through a menu array, skipping the +contents of submenus and invisible items. There are two calls so that +you can advance through const and non-const data. + +</body> +</html> diff --git a/documentation/Fl_Menu_Window.html b/documentation/Fl_Menu_Window.html new file mode 100644 index 000000000..a58017f96 --- /dev/null +++ b/documentation/Fl_Menu_Window.html @@ -0,0 +1,59 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Menu_Window">class Fl_Menu_Window</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Single_Window">Fl_Single_Window</a> + | + +----<b>Fl_Menu_Window</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Menu_Window.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Menu_Window</tt> widget is a window type used for menus. By +default the window is drawn in the hardware overlay planes if they are +available so that the menu don't force the rest of the window to +redraw. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Menu_Window.Fl_Menu_Window">Fl_Menu_Window</a> + <li><a href="#Fl_Menu_Window.~Fl_Menu_Window">~Fl_Menu_Window</a> + <li><a href="#Fl_Menu_Window.clear_overlay">clear_overlay</a> + <li><a href="#Fl_Menu_Window.set_overlay">set_overlay</a> +</ul> + +<h4><a name="Fl_Menu_Window.Fl_Menu_Window">Fl_Menu_Window::Fl_Menu_Window(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Menu_Window</tt> widget using the given position, size, and +label string. + +<h4><a name="Fl_Menu_Window.~Fl_Menu_Window">virtual Fl_Menu_Window::~Fl_Menu_Window()</a></h4> + +Destroys the window and all of its children. + +<h4><a name="Fl_Menu_Window.clear_overlay">Fl_Menu_Window::clear_overlay();</a></h4> + +Tells FLTK to use normal drawing planes instead of overlay planes. This is +usually necessary if your menu contains multi-color pixmaps. + +<h4><a name="Fl_Menu_Window.set_overlay">Fl_Menu_Window::set_overlay()</a></h4> + +Tells FLTK to use hardware overlay planes if they are available. + +</body> +</html> diff --git a/documentation/Fl_Multi_Browser.html b/documentation/Fl_Multi_Browser.html new file mode 100644 index 000000000..fb868c42d --- /dev/null +++ b/documentation/Fl_Multi_Browser.html @@ -0,0 +1,73 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Multi_Browser">class Fl_Multi_Browser</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Browser">Fl_Browser</a> + | + +----<b>Fl_Multi_Browser</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Multi_Browser.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Multi_Browser</tt> class is a subclass of +<tt>Fl_Browser</tt> which lets the user select any set of the lines. +The user interface is Macintosh style: clicking an item turns off all +the others and selects that one, dragging selects all the items the +mouse moves over, and shift + click toggles the items. This is +different then how forms did it. Normally the callback is done when +the user releases the mouse, but you can change this with +<tt>when()</tt>. + +<p>See <a href="#Fl_Browser"><tt>Fl_Browser</tt></a> for methods to add +and remove lines from the browser. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Multi_Browser.Fl_Multi_Browser">Fl_Multi_Browser</a> + <li><a href="#Fl_Multi_Browser.~Fl_Multi_Browser">~Fl_Multi_Browser</a> + <li><a href="#Fl_Multi_Browser.deselect">deselect</a> + <li><a href="#Fl_Multi_Browser.select">select</a> + <li><a href="#Fl_Multi_Browser.value">value</a> +</ul> + +<h4><a name="Fl_Multi_Browser.Fl_Multi_Browser">Fl_Multi_Browser::Fl_Multi_Browser(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Multi_Browser</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_DOWN_BOX</tt>. + +<h4><a name="Fl_Multi_Browser.~Fl_Multi_Browser">virtual Fl_Multi_Browser::~Fl_Multi_Browser()</a></h4> + +The destructor <i>also deletes all the items in the list</i>. + +<h4><a name="Fl_Multi_Browser.deselect">int Fl_Browser::deselect()</a></h4> + +Deselects all lines. + +<h4><a name="Fl_Multi_Browser.select">int Fl_Browser::select(int,int=1)<br> +int Fl_Browser::selected(int) const</a></h4> + +Selects one or more lines or gets the current selection state of a line. + +<h4><a name="Fl_Multi_Browser.value">int Fl_Browser::value() const<br> +void Fl_Browser::value(int)</a></h4> + +Selects a single line or gets the last toggled line. This returns zero +if no line has been toggled, so be aware that this can happen in a callback. + +</body> +</html> diff --git a/documentation/Fl_Multiline_Input.html b/documentation/Fl_Multiline_Input.html new file mode 100644 index 000000000..1b157eace --- /dev/null +++ b/documentation/Fl_Multiline_Input.html @@ -0,0 +1,53 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Multiline_Input">class Fl_Multiline_Input</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Input">Fl_Input</a> + | + +----<b>Fl_Multiline_Input</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Input.H> +</pre></ul> + +<h3>Description</h3> + +This input field displays '\n' characters as new lines rather than ^J, +and accepts the Return, Tab, and up and down arrow keys. This is for +editing multiline text. + +<p>This is far from the nirvana of text editors, and is probably only +good for small bits of text, 10 lines at most. I think FLTK can be +used to write a powerful text editor, but it is not going to be a +built-in feature. Powerful text editors in a toolkit are a big source +of bloat. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Multiline_Input.Fl_Multiline_Input">Fl_Multiline_Input</a> + <li><a href="#Fl_Multiline_Input.~Fl_Multiline_Input">~Fl_Multiline_Input</a> +</ul> + +<h4><a name="Fl_Multiline_Input.Fl_Multiline_Input">Fl_Multiline_Input::Fl_Multiline_Input(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Multiline_Input</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_DOWN_BOX</tt>. + +<h4><a name="Fl_Multiline_Input.~Fl_Multiline_Input">virtual Fl_Multiline_Input::~Fl_Multiline_Input()</a></h4> + +Destroys the widget and any value associated with it. + +</body> +</html> diff --git a/documentation/Fl_Multiline_Output.html b/documentation/Fl_Multiline_Output.html new file mode 100644 index 000000000..d6d53bd24 --- /dev/null +++ b/documentation/Fl_Multiline_Output.html @@ -0,0 +1,46 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Multiline_Output">class Fl_Multiline_Output</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Output">Fl_Output</a> + | + +----<b>Fl_Multiline_Output</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Multiline_Output.H> +</pre></ul> + +<h3>Description</h3> + +This widget is a subclass of <tt>Fl_Output</tt> that displays multiple lines +of text. It also displays tab characters as whitespace to the next column. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Multiline_Output.Fl_Multiline_Output">Fl_Multiline_Output</a> + <li><a href="#Fl_Multiline_Output.~Fl_Multiline_Output">~Fl_Multiline_Output</a> +</ul> + +<h4><a name="Fl_Multiline_Output.Fl_Multiline_Output">Fl_Multiline_Output::Fl_Multiline_Output(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Multiline_Output</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_DOWN_BOX</tt>. + +<h4><a name="Fl_Multiline_Output.~Fl_Multiline_Output">virtual Fl_Multiline_Output::~Fl_Multiline_Output()</a></h4> + +Destroys the widget and any value associated with it. + +</body> +</html> diff --git a/documentation/Fl_Output.html b/documentation/Fl_Output.html new file mode 100644 index 000000000..0039eebb0 --- /dev/null +++ b/documentation/Fl_Output.html @@ -0,0 +1,108 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Output">class Fl_Output</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Input_">Fl_Input_</a> + | + +----<b>Fl_Output</b> + | + +----<a href="#Fl_Multiline_Output">Fl_Multiline_Output</a> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Output.H> +</pre></ul> + +<h3>Description</h3> + +This widget displays a piece of text. When you set the <tt>value()</tt>, +<tt>Fl_Output</tt> does a <tt>strcpy()</tt> to it's own storage, which is useful for +program-generated values. The user may select portions of the text +using the mouse and paste the contents into other fields or programs. + +<p><img src=text.gif> + +<p>There is a single subclass, <a +href="#Fl_Multiline_Output">Fl_Multiline_Output</a>, which allows you to +display multiple lines of text. + +<p>The text may contain any characters except \0, and will correctly +display anything, using ^X notation for unprintable control characters +and \nnn notation for unprintable characters with the high bit set. It +assummes the font can draw any characters in the ISO-Latin1 character +set. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Output.Fl_Output">Fl_Output</a> + <li><a href="#Fl_Output.~Fl_Output">~Fl_Output</a> + <li><a href="#Fl_Output.cursor_color">cursor_color</a> + <li><a href="#Fl_Output.index">index</a> + <li><a href="#Fl_Output.size">size</a> + <li><a href="#Fl_Output.textcolor">textcolor</a> + <li><a href="#Fl_Output.textfont">textfont</a> + <li><a href="#Fl_Output.textsize">textsize</a> + <li><a href="#Fl_Output.value">value</a> +</ul> + +<h4><a name="Fl_Output.Fl_Output">Fl_Output::Fl_Output(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Output</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_DOWN_BOX</tt>. + +<h4><a name="Fl_Output.~Fl_Output">virtual Fl_Output::~Fl_Output()</a></h4> + +Destroys the widget and any value associated with it. + +<h4><a name="Fl_Output.value">const char *Fl_Output::value() const<br> +int Fl_Output::value(const char*)<br> +int Fl_Output::value(const char*, int)</a></h4> + +The first form returns the current value, which is a pointer to the +internal buffer and is valid only until the value is changed. + +<p>The second two forms change the text and set the mark and the point +to the end of it. The string is copied to the internal buffer. Passing +<tt>NULL</tt> is the same as "". This returns non-zero if the new +value is different than the current one. You can use the second +version to directly set the length if you know it already or want to +put nul's in the text. + +<h4><a name="Fl_Output.size">int Fl_Output::size() const</a></h4> + +Returns the number of characters in <tt>value()</tt>. This may be greater than +<tt>strlen(value())</tt> if there are nul characters in it. + +<h4><a name="Fl_Output.index">char Fl_Output::index(int) const</a></h4> + +Same as <tt>value()[n]</tt>, but may be faster in plausible implementations. +No bounds checking is done. + +<h4><a name="Fl_Output.textcolor">Fl_Color Fl_Output::textcolor() const<br> +void Fl_Output::textcolor(Fl_Color)</a></h4> + +Gets or sets the color of the text in the input field. + +<h4><a name="Fl_Output.textfont">Fl_Font Fl_Output::textfont() const<br> +void Fl_Output::textfont(Fl_Font)</a></h4> + +Gets or sets the font of the text in the input field. + +<h4><a name="Fl_Output.textsize">uchar Fl_Output::textsize() const<br> +void Fl_Output::textsize(uchar)</a></h4> + +Gets or sets the size of the text in the input field. + +</body> +</html> diff --git a/documentation/Fl_Overlay_Window.html b/documentation/Fl_Overlay_Window.html new file mode 100644 index 000000000..b9b0218de --- /dev/null +++ b/documentation/Fl_Overlay_Window.html @@ -0,0 +1,70 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Overlay_Window">class Fl_Overlay_Window</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Double_Window">Fl_Double_Window</a> + | + +----<b>Fl_Overlay_Window</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Overlay_Window.H> +</pre></ul> + +<h3>Description</h3> + +This window provides double buffering and also the ability to draw the +"overlay" which is another picture placed on top of the main image. +The overlay is designed to be a rapidly-changing but simple graphic +such as a mouse selection box. <tt>Fl_Overlay_Window</tt> uses the +overlay planes provided by your graphics hardware if they are available. + +<p>If no hardware support is found the overlay is simulated by drawing +directly into the on-screen copy of the double-buffered window, and +"erased" by copying the backbuffer over it again. This means the +overlay will blink if you change the image in the window. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Overlay_Window.Fl_Overlay_Window">Fl_Overlay_Window</a> + <li><a href="#Fl_Overlay_Window.~Fl_Overlay_Window">~Fl_Overlay_Window</a> + <li><a href="#Fl_Overlay_Window.draw_overlay">draw_overlay</a> + <li><a href="#Fl_Overlay_Window.redraw_overlay">redraw_overlay</a> +</ul> + +<h4><a name="Fl_Overlay_Window.Fl_Overlay_Window">Fl_Overlay_Window::Fl_Overlay_Window(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Overlay_Window</tt> widget using the given position, size, and +label (title) string. + +<h4><a name="Fl_Overlay_Window.~Fl_Overlay_Window">virtual Fl_Overlay_Window::~Fl_Overlay_Window()</a></h4> + +Destroys the window and all child widgets. + +<h4><a name="Fl_Overlay_Window.">virtual void Fl_Overlay_Window::draw_overlay() = 0</a></h4> + +You must subclass <tt>Fl_Overlay_Window</tt> and provide this method. It is +just like a <tt>draw()</tt> method, except it draws the overlay. The overlay +will have already been "cleared" when this is called. You can use any +of the routines described in <a href="#Drawing"><FL/fl_draw.H></a>. + +<h4><a name="Fl_Overlay_Window.">void Fl_Overlay_Window::redraw_overlay()</a></h4> + +Call this to indicate that the overlay data has changed and needs to +be redrawn. The overlay will be clear until the first time this is +called, so if you want an initial display you must call this after +calling <tt>show()</tt>. + +</body> +</html> diff --git a/documentation/Fl_Pack.html b/documentation/Fl_Pack.html new file mode 100644 index 000000000..b7e70cb9e --- /dev/null +++ b/documentation/Fl_Pack.html @@ -0,0 +1,103 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Pack">class Fl_Pack</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Group">Fl_Group</a> + | + +----<b>Fl_Pack</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Pack.H> +</pre></ul> + +<h3>Description</h3> + +This widget was designed to add the functionality of compressing +and aligning widgets. + +<p>If <tt>type()</tt> is <tt>FL_HORIZONTAL</tt> all the children are resized to the +height of the <tt>Fl_Pack</tt>, and are moved next to each other horizontally. +If <tt>type()</tt> is not <tt>FL_HORIZONTAL</tt> then the children are resized to the +width and are stacked below each other. Then the <tt>Fl_Pack</tt> resizes +itself to surround the child widgets. + +<p>This widget is needed for the <a href="#Fl_Tab"><tt>Fl_Tab</tt></a>. In +addition you may want to put the <tt>Fl_Pack</tt> inside an +<a href="#Fl_Scroll"><tt>Fl_Scroll</tt></a>. + +<h3>Methods</h3> + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Pack.Fl_Pack">Fl_Pack</a> + <li><a href="#Fl_Pack.~Fl_Pack">~Fl_Pack</a> + <li><a href="#Fl_Pack.add">add</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Pack.add_resizeable">add_resizeable</a> + <li><a href="#Fl_Pack.array">array</a> + <li><a href="#Fl_Pack.begin">begin</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Pack.child">child</a> + <li><a href="#Fl_Pack.children">children</a> + <li><a href="#Fl_Pack.current">current</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Pack.end">end</a> + <li><a href="#Fl_Pack.find">find</a> + <li><a href="#Fl_Pack.insert">insert</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Pack.remove">remove</a> + <li><a href="#Fl_Pack.resizeable">resizeable</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4><a name="Fl_Pack.Fl_Pack">Fl_Pack::Fl_Pack(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Pack</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_NO_BOX</tt>. + +<h4><a name="Fl_Pack.~Fl_Pack">virtual Fl_Pack::~Fl_Pack()</a></h4> + +The destructor <i>also deletes all the children</i>. This allows a +whole tree to be deleted at once, without having to keep a pointer to all +the children in the user code. A kludge has been done so the +<tt>Fl_Pack</tt> and all of it's children can be automatic (local) +variables, but you must declare the <tt>Fl_Pack</tt> <i>first</i>, so +that it is destroyed last. + +<h4><a name="Fl_Pack.spacing">int Fl_Pack::spacing() const<br> +void Fl_Pack::spacing(int)</a></h4> + +Gets or sets the number of extra pixels of blank space that are added between +the children. + +</body> +</html> diff --git a/documentation/Fl_Positioner.html b/documentation/Fl_Positioner.html new file mode 100644 index 000000000..30c3ac288 --- /dev/null +++ b/documentation/Fl_Positioner.html @@ -0,0 +1,97 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Positioner">class Fl_Positioner</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Positioner</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Positioner.H> +</pre></ul> + +<h3>Description</h3> + +This class is provided for Forms compatibility. It provides 2D input. +It would be useful if this could be put atop another widget so that the +crosshairs are on top, but this is not implemented. The color of the +crosshairs is <tt>selection_color()</tt>. + +<p><img src=positioner.gif> + +<h3>Methods</h3> + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Positioner.Fl_Positioner">Fl_Positioner</a> + <li><a href="#Fl_Positioner.~Fl_Positioner">~Fl_Positioner</a> + <li><a href="#Fl_Positioner.value">value</a> + <li><a href="#Fl_Positioner.xbounds">xbounds</a> + <li><a href="#Fl_Positioner.xstep">xstep</a> + <li><a href="#Fl_Positioner.xvalue">xvalue</a> + <li><a href="#Fl_Positioner.ybounds">ybounds</a> + <li><a href="#Fl_Positioner.ystep">ystep</a> + <li><a href="#Fl_Positioner.yvalue">yvalue</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4><a name="Fl_Positioner.Fl_Positioner">Fl_Positioner::Fl_Positioner(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Positioner</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_NO_BOX</tt>. + +<h4><a name="Fl_Positioner.~Fl_Positioner">virtual Fl_Positioner::~Fl_Positioner()</a></h4> + +Deletes the widget. + +<h4><a name="Fl_Positioner.value">void Fl_Positioner::value(float *x, float *y) const</a></h4> + +Returns the current position in <tt>x</tt> and <tt>y</tt>. + +<h4><a name="Fl_Positioner.xbounds">void xbounds(float *xmin, float *xmax)<br> +void xbounds(float xmin, float xmax)</a></h4> + +Gets or sets the X axis bounds. + +<h4><a name="Fl_Positioner.xstep">void xstep(float x)</a></h4> + +Sets the stepping value for the X axis. + +<h4><a name="Fl_Positioner.xvalue">float Fl_Positioner::xvalue(void) const<br> +void Fl_Positioner::xvalue(float x)</a></h4> + +Gets or sets the X axis coordinate. + +<h4><a name="Fl_Positioner.ybounds">void ybounds(float *ymin, float *ymay)<br> +void ybounds(float ymin, float ymay)</a></h4> + +Gets or sets the Y axis bounds. + +<h4><a name="Fl_Positioner.ystep">void ystep(float y)</a></h4> + +Sets the stepping value for the Y axis. + +<h4><a name="Fl_Positioner.yvalue">float Fl_Positioner::yvalue(void) const<br> +void Fl_Positioner::yvalue(float y)</a></h4> + +Gets or sets the Y axis coordinate. + +</body> +</html> diff --git a/documentation/Fl_Repeat_Button.html b/documentation/Fl_Repeat_Button.html new file mode 100644 index 000000000..60129ffdc --- /dev/null +++ b/documentation/Fl_Repeat_Button.html @@ -0,0 +1,45 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Repeat_Button">class Fl_Repeat_Button</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre><a href="#Fl_Button">Fl_Button</a> + | + +----<b>Fl_Repeat_Button</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre>#include <FL/Fl_Repeat_Button.H></pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Repeat_Button</tt> is a subclass of <tt>Fl_Button</tt> that +generates a callback when it is pressed and then repeatedly generates +callbacks as long as it is held down. The speed of the repeat is fixed +and depends on the implementation. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Repeat_Button.Fl_Repeat_Button">Fl_Repeat_Button</a> + <li><a href="#Fl_Repeat_Button.~Fl_Repeat_Button">~Fl_Repeat_Button</a> +</ul> + +<h4><a name="Fl_Repeat_Button.Fl_Repeat_Button">Fl_Repeat_Button::Fl_Repeat_Button(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Repeat_Button</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_UP_BOX</tt>. + +<h4><a name="Fl_Repeat_Button.~Fl_Repeat_Button">virtual Fl_Repeat_Button::~Fl_Repeat_Button()</a></h4> + +Deletes the button. + +</body> +</html> diff --git a/documentation/Fl_Return_Button.html b/documentation/Fl_Return_Button.html new file mode 100644 index 000000000..8ecfbef31 --- /dev/null +++ b/documentation/Fl_Return_Button.html @@ -0,0 +1,44 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Return_Button">class Fl_Return_Button</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre><a href="#Fl_Button">Fl_Button</a> + | + +----<b>Fl_Return_Button</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre>#include <FL/Fl_Return_Button.H></pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Return_Button</tt> is a subclass of <tt>Fl_Button</tt> that +generates a callback when it is pressed or when the user presses the +Enter key. A carriage-return symbol is drawn next to the button label. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Return_Button.Fl_Return_Button">Fl_Return_Button</a> + <li><a href="#Fl_Return_Button.~Fl_Return_Button">~Fl_Return_Button</a> +</ul> + +<h4><a name="Fl_Return_Button.Fl_Return_Button">Fl_Return_Button::Fl_Return_Button(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Return_Button</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_UP_BOX</tt>. + +<h4><a name="Fl_Return_Button.~Fl_Return_Button">virtual Fl_Return_Button::~Fl_Return_Button()</a></h4> + +Deletes the button. + +</body> +</html> diff --git a/documentation/Fl_Roller.gif b/documentation/Fl_Roller.gif Binary files differnew file mode 100644 index 000000000..9e53cff4a --- /dev/null +++ b/documentation/Fl_Roller.gif diff --git a/documentation/Fl_Roller.html b/documentation/Fl_Roller.html new file mode 100644 index 000000000..5bc7f0c74 --- /dev/null +++ b/documentation/Fl_Roller.html @@ -0,0 +1,46 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Roller">class Fl_Roller</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Valuator">Fl_Valuator</a> + | + +----<b>Fl_Roller</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Roller.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Roller</tt> widget is a "dolly" control commonly used to +move 3D objects. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Roller.Fl_Roller">Fl_Roller</a> + <li><a href="#Fl_Roller.~Fl_Roller">~Fl_Roller</a> +</ul> + +<h4><a name="Fl_Roller.Fl_Roller">Fl_Roller::Fl_Roller(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Roller</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_NO_BOX</tt>. + +<h4><a name="Fl_Roller.~Fl_Roller">virtual Fl_Roller::~Fl_Roller()</a></h4> + +Destroys the valuator. + +</body> +</html> diff --git a/documentation/Fl_Round_Button.html b/documentation/Fl_Round_Button.html new file mode 100644 index 000000000..648d17a0a --- /dev/null +++ b/documentation/Fl_Round_Button.html @@ -0,0 +1,53 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Round_Button">class Fl_Round_Button</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Button">Fl_Button</a> + | + +----<b>Fl_Round_Button</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Round_Button.H> +</pre></ul> + +<h3>Description</h3> + +Buttons generate callbacks when they are clicked by the user. You +control exactly when and how by changing the values for <tt>type()</tt> and +<tt>when()</tt>. + +<P>The <tt>Fl_Round_Button</tt> subclass display the "on" state by +turning on a light, rather than drawing pushed in. The shape of the +"light" is initially set to FL_ROUND_DOWN_BOX. The color of the +light when on is controlled with <tt>selection_color()<tt>, which defaults to +FL_RED. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Round_Button.Fl_Round_Button">Fl_Round_Button</a> + <li><a href="#Fl_Round_Button.~Fl_Round_Button">~Fl_Round_Button</a> +</ul> + +<h4><a name="Fl_Round_Button.Fl_Round_Button">Fl_Round_Button::Fl_Round_Button(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Round_Button</tt> widget using the given position, +size, and label string. + +<h4><a name="Fl_Round_Button.~Fl_Round_Button">Fl_Round_Button::~Fl_Round_Button()</a></h4> + +The destructor deletes the check button. + +</body> +</html> diff --git a/documentation/Fl_Scroll.gif b/documentation/Fl_Scroll.gif Binary files differnew file mode 100644 index 000000000..c1a959578 --- /dev/null +++ b/documentation/Fl_Scroll.gif diff --git a/documentation/Fl_Scroll.html b/documentation/Fl_Scroll.html new file mode 100644 index 000000000..41136476c --- /dev/null +++ b/documentation/Fl_Scroll.html @@ -0,0 +1,135 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Scroll">class Fl_Scroll</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Group">Fl_Group</a> + | + +----<b>Fl_Scroll</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Scroll.H> +</pre></ul> + +<h3>Description</h3> + +This container widget lets you maneuver around a set of widgets +much larger than your window. If the child widgets are larger than +the size of this object then scrollbars will appear so that you can +scroll over to them: + +<p><img src=Fl_Scroll.gif> + +<p>If all of the child widgets are packed together into a solid +rectangle then you want to set <tt>box()</tt> to <tt>FL_NO_BOX</tt> or +one of the <tt>_FRAME</tt> types. This will result in the best output. +However, if the child widgets are a sparse arrangment you must set +<tt>box()</tt> to a real <tt>_BOX</tt> type. This can result in some +blinking during redrawing, but that can be solved by using a +<tt>Fl_Double_Window</tt>. + +<p>This widget can also be used to pan around a single child widget +"canvas". This child widget should be of your own class, with a +<tt>draw()</tt> method that draws the contents. The scrolling is done +by changing the <tt>x()</tt> and <tt>y()</tt> of the widget, so this +child must use the <tt>x()</tt> and <tt>y()</tt> to position it's +drawing. To speed up drawing it should test <a +href=fl_clip><tt>fl_clip()</tt></a>. + +<p>Another very useful child is a single <a +href="#Fl_Pack"><tt>Fl_Pack</tt></a>, which is itself a group that +packs it's children together and changes size to surround them. +Filling the <tt>Fl_Pack</tt> with <a href="#Fl_Tab"><tt>Fl_Tab</tt></a> +groups (and then putting normal widgets inside those) gives you a very +powerful scrolling list of individually-openable panels. + +<p>Fluid lets you create these, but you can only lay out objects that +fit inside the <tt>Fl_Scroll</tt> without scrolling. Be sure to leave +space for the scrollbars, as Fluid won't show these either. + +<p><i>You cannot use <tt>Fl_Window</tt> as a child of this since the +clipping is not conveyed to it when drawn, and it will draw over the +scrollbars and neighboring objects.</i> + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Scroll.Fl_Scroll">Fl_Scroll</a> + <li><a href="#Fl_Scroll.~Fl_Scroll">~Fl_Scroll</a> + <li><a href="#Fl_Scroll.align">align</a> + <li><a href="#Fl_Scroll.position">position</a> + <li><a href="#Fl_Scroll.type">type</a> + <li><a href="#Fl_Scroll.xposition">xposition</a> + <li><a href="#Fl_Scroll.yposition">yposition</a> +</ul> + +<h4><a name="Fl_Scroll.Fl_Scroll">Fl_Scroll::Fl_Scroll(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Scroll</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_NO_BOX</tt>. + +<h4><a name="Fl_Scroll.~Fl_Scroll">virtual Fl_Scroll::~Fl_Scroll()</a></h4> + +The destructor <i>also deletes all the children</i>. This allows a +whole tree to be deleted at once, without having to keep a pointer to all +the children in the user code. A kludge has been done so the +<tt>Fl_Scroll</tt> and all of it's children can be automatic (local) +variables, but you must declare the <tt>Fl_Scroll</tt> <i>first</i>, so +that it is destroyed last. + +<h4><a name="Fl_Scroll.type">void Fl_Widget::type(int)</a></h4> + +By default you can scroll in both directions, and the scrollbars +disappear if the data will fit in the area of the scroll. <tt>type()</tt> +can change this: + +<ul> + <li><tt>0</tt> - No scrollbars + + <li><tt>Fl_Scroll::HORIZONTAL</tt> - Only a horizontal scrollbar. + + <li><tt>Fl_Scroll::VERTICAL</tt> - Only a vertical scrollbar. + + <li><tt>Fl_Scroll::BOTH</tt> - The default is both scrollbars. + + <li><tt>Fl_Scroll::HORIZONTAL_ALWAYS</tt> - Horizontal scrollbar + always on, vertical always off. + + <li><tt>Fl_Scroll::VERTICAL_ALWAYS</tt> - Vertical scrollbar always on, + horizontal always off. + + <li><tt>Fl_Scroll::BOTH_ALWAYS</tt> - Both always on. +</ul> + +<h4><a name="Fl_Scroll.align">void Fl_Scroll::scrollbar.align(int)<br> +void Fl_Scroll::hscrollbar.align(int)</a></h4> + +This is used to change what side the scrollbars are drawn on. If the +<tt>FL_ALIGN_LEFT</tt> bit is on, the vertical scrollbar is on the +left. If the <tt>FL_ALIGN_TOP</tt> bit is on, the horizontal scrollbar +is on the top. + +<h4><a name="Fl_Scroll.xposition">int Fl_Scroll::xposition() const</a></h4> + +Gets the current horizontal scrolling position. + +<h4><a name="Fl_Scroll.yposition">int Fl_Scroll::yposition() const</a></h4> + +Gets the current vertical scrolling position. + +<h4><a name="Fl_Scroll.position">void Fl_Scroll::position(int w, int h)</a></h4> + +Sets the upper-lefthand corner of the scrolling region. + +</body> +</html> diff --git a/documentation/Fl_Scrollbar.html b/documentation/Fl_Scrollbar.html new file mode 100644 index 000000000..535831546 --- /dev/null +++ b/documentation/Fl_Scrollbar.html @@ -0,0 +1,78 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Scrollbar">class Fl_Scrollbar</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Slider">Fl_Slider</a> + | + +----<b>Fl_Scrollbar</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Scrollbar.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Scrollbar</tt> widget displays a slider with arrow buttons +at the ends of the scrollbar. Clicking on the arrows move up/left and +down/right by <tt>linesize()</tt>. Scrollbars also accept +<tt>FL_SHORTCUT</tt> events: the arrows move by <tt>linesize()</tt>, +and vertical scrollbars take Page Up/Down (they move by the page size +minus <tt>linesize()</tt>) and Home/End (they jump to the top or +bottom). + +<p>Scrollbars have <tt>step(1)</tt> preset (they always return +integers). If desired you can set the <tt>step()</tt> to non-integer +values. You will then have to use casts to get at the floating-point +versions of <tt>value()</tt> from <tt>Fl_Slider</tt>. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Scrollbar.Fl_Scrollbar">Fl_Scrollbar</a> + <li><a href="#Fl_Scrollbar.~Fl_Scrollbar">~Fl_Scrollbar</a> + <li><a href="#Fl_Scrollbar.linesize">linesize</a> + <li><a href="#Fl_Scrollbar.value">value</a> +</ul> + +<h4><a name="Fl_Scrollbar.Fl_Scrollbar">Fl_Scrollbar::Fl_Scrollbar(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Scrollbar</tt> widget using the given position, +size, and label string. You need to do <tt>type(FL_HORIZONTAL)</tt> if +you want a horizontal scrollbar. + +<h4><a name="Fl_Scrollbar.~Fl_Scrollbar">virtual Fl_Scrollbar::~Fl_Scrollbar()</a></h4> + +Destroys the valuator. + +<h4><a name="Fl_Scrollbar.linesize">int Fl_Scrollbar::linesize() const<br> +void Fl_Scrollbar::linesize(int i)</a></h4> + +This number controls how big the steps are that the arrow keys do. In +addition page up/down move by the size last sent to <tt>value()</tt> +minus one <tt>linesize()</tt>. The default is 16. + +<h4><a name="Fl_Scrollbar.value">int Fl_Scrollbar::value()<br> +int Fl_Scrollbar::value(int position, int size, int top, int total)</a></h4> + +The first form returns the integer value of the scrollbar. You can get +the floating point value with <tt>Fl_Slider::value()</tt>. + +The second form sets <tt>value()</tt>, <tt>range()</tt>, and +<tt>slider_size()</tt> to make a variable-sized scrollbar. You should +call this every time your window changes size, your data changes size, +or your scroll position changes (even if in response to a callback from +this scrollbar). All necessary calls to <tt>redraw()</tt> are done. + +</body> +</html> diff --git a/documentation/Fl_Secret_Input.html b/documentation/Fl_Secret_Input.html new file mode 100644 index 000000000..ee62a6ec8 --- /dev/null +++ b/documentation/Fl_Secret_Input.html @@ -0,0 +1,47 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Secret_Input">class Fl_Secret_Input</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Input">Fl_Input</a> + | + +----<b>Fl_Secret_Input</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Input.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Secret_Input</tt> class is a subclass of <tt>Fl_Input</tt> that +displays its input as a string of asterisks. This subclass is usually used +to recieve passwords and other "secret" information. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Secret_Input.Fl_Secret_Input">Fl_Secret_Input</a> + <li><a href="#Fl_Secret_Input.~Fl_Secret_Input">~Fl_Secret_Input</a> +</ul> + +<h4><a name="Fl_Secret_Input.Fl_Secret_Input">Fl_Secret_Input::Fl_Secret_Input(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Secret_Input</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_DOWN_BOX</tt>. + +<h4><a name="Fl_Secret_Input.~Fl_Secret_Input">virtual Fl_Secret_Input::~Fl_Secret_Input()</a></h4> + +Destroys the widget and any value associated with it. + +</body> +</html> diff --git a/documentation/Fl_Select_Browser.html b/documentation/Fl_Select_Browser.html new file mode 100644 index 000000000..b29fbb944 --- /dev/null +++ b/documentation/Fl_Select_Browser.html @@ -0,0 +1,72 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Select_Browser">class Fl_Select_Browser</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Browser">Fl_Browser</a> + | + +----<b>Fl_Select_Browser</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Select_Browser.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Select_Browser</tt> class is a subclass of <tt>Fl_Browser</tt> +which lets the user select a single item, or no items by clicking on +the empty space. As long as the mouse button is held down the item +pointed to by it is highlighted. Normally the callback is done when the +user presses the mouse, but you can change this with <tt>when()</tt>. + +<p>See <a href="#Fl_Browser"><tt>Fl_Browser</tt></a> for methods to add +and remove lines from the browser. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Select_Browser.Fl_Select_Browser">Fl_Select_Browser</a> + <li><a href="#Fl_Select_Browser.~Fl_Select_Browser">~Fl_Select_Browser</a> + <li><a href="#Fl_Select_Browser.deselect">deselect</a> + <li><a href="#Fl_Select_Browser.select">select</a> + <li><a href="#Fl_Select_Browser.value">value</a> +</ul> + +<h4><a name="Fl_Select_Browser.Fl_Select_Browser">Fl_Select_Browser::Fl_Select_Browser(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Select_Browser</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_DOWN_BOX</tt>. + +<h4><a name="Fl_Select_Browser.~Fl_Select_Browser">virtual Fl_Select_Browser::~Fl_Select_Browser()</a></h4> + +The destructor <i>also deletes all the items in the list</i>. + +<h4><a name="Fl_Select_Browser.deselect">int Fl_Browser::deselect()</a></h4> + +Same as <tt>value(0)</tt>. + +<h4><a name="Fl_Select_Browser.select">int Fl_Browser::select(int,int=1)<br> +int Fl_Browser::selected(int) const</a></h4> + +You can use these for compatibility with +<a href="#Fl_Multi_Browser"><tt>Fl_Multi_Browser</tt></a>. If you +turn on the selection of more than one line the results are +unpredictable. + +<h4><a name="Fl_Select_Browser.value">int Fl_Browser::value() const</a></h4> + +Returns the number of the highlighted item, or zero if none. Notice +that this is going to be zero except <i>during</i> a callback! + +</body> +</html> diff --git a/documentation/Fl_Single_Window.html b/documentation/Fl_Single_Window.html new file mode 100644 index 000000000..9f0e297ea --- /dev/null +++ b/documentation/Fl_Single_Window.html @@ -0,0 +1,49 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Single_Window">class Fl_Single_Window</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Window">Fl_Window</a> + | + +----<b>Fl_Single_Window</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Single_Window.H> +</pre></ul> + +<h3>Description</h3> + +This is the same as <tt>Fl_Window<tt>. However, it is possible that +some implementations will provide double-buffered windows by default. +This subclass can be used to force single-buffering. This may be +useful for modifying existing programs that use incremental update, or +for some types of image data, such as a movie flipbook. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Single_Window.Fl_Single_Window">Fl_Single_Window</a> + <li><a href="#Fl_Single_Window.~Fl_Single_Window">~Fl_Single_Window</a> +</ul> + +<h4><a name="Fl_Single_Window.Fl_Single_Window">Fl_Single_Window::Fl_Single_Window(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Single_Window</tt> widget using the given position, size, and +label (title) string. + +<h4><a name="Fl_Single_Window.~Fl_Single_Window">virtual Fl_Single_Window::~Fl_Single_Window()</a></h4> + +Destroys the window and all child widgets. + +</body> +</html> diff --git a/documentation/Fl_Slider.html b/documentation/Fl_Slider.html new file mode 100644 index 000000000..295c06e0f --- /dev/null +++ b/documentation/Fl_Slider.html @@ -0,0 +1,101 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Slider">class Fl_Slider</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Valuator">Fl_Valuator</a> + | + +----<b>Fl_Slider</b> + | + +----<a href="#Fl_Scrollbar">Fl_Scrollbar</a>, <a href="#Fl_Value_Slider">Fl_Value_Slider</a> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Slider.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Slider</tt> widget contains a sliding knob inside a box. It +if often used as a scrollbar. Moving the box all the way to the +top/left sets it to the <tt>minimum()</tt>, and to the bottom/right to +the <tt>maximum()</tt>. The <tt>minimum()</tt> may be greater than the +<tt>maximum()</tt> to reverse the slider direction. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Slider.Fl_Slider">Fl_Slider</a> + <li><a href="#Fl_Slider.~Fl_Slider">~Fl_Slider</a> + <li><a href="#Fl_Slider.scrollvalue">scrollvalue</a> + <li><a href="#Fl_Slider.slider">slider</a> + <li><a href="#Fl_Slider.slider_size">slider_size</a> + <li><a href="#Fl_Slider.type">type</a> +</ul> + +<h4><a name="Fl_Slider.Fl_Slider">Fl_Slider::Fl_Slider(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Slider</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_NO_BOX</tt>. + +<h4><a name="Fl_Slider.~Fl_Slider">virtual Fl_Slider::~Fl_Slider()</a></h4> + +Destroys the valuator. + +<h4><a name="Fl_Slider.scrollvalue">int Fl_Slider::scrollvalue(int windowtop, int windowsize, int first, int totalsize)</a></h4> + +Returns <a href="#Fl_Scrollbar.value"><tt>Fl_Scrollbar::value()</tt></a>. + +<h4><a name="Fl_Slider.">Fl_Boxtype Fl_Slider::slider() const<br> +void Fl_Slider::slider(Fl_Boxtype)</a></h4> + +Set the type of box to draw for the moving part of the slider. The +color of the moving part (or of the notch in it for the nice sliders) +is controlled by <tt>selection_color()</tt>. The default value of zero +causes the slider to figure out what to draw from <tt>box()</tt>. + +<h4><a name="Fl_Slider.slider_size">float Fl_Slider::slider_size() const<br> +void Fl_Slider::slider_size(float)</a></h4> + +Get or set the dimensions of the moving piece of slider. This is the +fraction of the size of the entire widget. If you set this to 1 then +the slider cannot move. The default value is .08. + +<p>For the "fill" sliders this is the size of the area around the end +that causes a drag effect rather than causing the slider to jump to +the mouse. + +<h4><a name="Fl_Slider.type">uchar Fl_Widget::type() const<br> +void Fl_Widget::type(uchar t)</a></h4> + +Setting this changes how the slider is drawn, which can be one of the following: + +<ul> + <li><tt>FL_VERTICAL</tt> - Draws a vertical slider (this is the default). + + <li><tt>FL_HORIZONTAL</tt> - Draws a horizontal slider. + + <li><tt>FL_VERT_FILL_SLIDER</tt> - Draws a filled vertical + slider, useful as a progress or value meter. + + <li><tt>FL_HOR_FILL_SLIDER</tt> - Draws a filled horizontal + slider, useful as a progress or value meter. + + <li><tt>FL_VERT_NICE_SLIDER</tt> - Draws a vertical slider with + a nice looking control knob. + + <li><tt>FL_HOR_NICE_SLIDER</tt> - Draws a horizontal slider with + a nice looking control knob. +</ul> + +</body> +</html> diff --git a/documentation/Fl_Tabs.html b/documentation/Fl_Tabs.html new file mode 100644 index 000000000..3018aeecd --- /dev/null +++ b/documentation/Fl_Tabs.html @@ -0,0 +1,85 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Tabs">class Fl_Tabs</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Group">Fl_Group</a> + | + +----<b>Fl_Tabs</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Tab.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Tabs</tt> widget is the "file card tabs" interface that +allows you to put lots and lots of buttons and switches in a panel, as +popularized by many toolkits. + +<p><img src=tabs.gif> + +<p>Clicking the tab makes a child <tt>visible()</tt> (by calling +<tt>show()</tt> on it) and all other children are invisible (by calling +<tt>hide()</tt> on them). Usually the children are <a +href="#Fl_Group"><tt>Fl_Group<tt></a> widgets containing several +widgets themselves. + +<p>Each child makes a card, and it's <tt>label()</tt> is printed on the +card tab (including the label font and style). The color of that child +is used to color the card as well. Currently this only draws nicely if +you set <a href="#Fl_Widget.box"><tt>box()</tt></a> to the default +<tt>FL_THIN_UP_BOX</tt> or to <tt>FL_FLAT_BOX</tt>, which gets rid of +the edges drawn on the sides and bottom. + +<p>The size of the tabs is controlled by the bounding box of the +children (there should be some space between the children and the edge +of the <tt>Fl_Tabs</tt>), and the tabs may be placed "inverted" on the +bottom, this is determined by which gap is larger. It is easiest to +lay this out in fluid, using the fluid browser to select each child +group and resize them until the tabs look the way you want them to. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Tab.Fl_Tab">Fl_Tab</a> + <li><a href="#Fl_Tab.~Fl_Tab">~Fl_Tab</a> + <li><a href="#Fl_Tab.value">value</a> +</ul> + +<h4><a name="Fl_Tab.Fl_Tab">Fl_Tab::Fl_Tab(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Tab</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_THIN_UP_BOX</tt>. + +<p>Use <a href="#Fl_Group.add"><tt>add(Fl_Widget *)</tt></a> to add +each child (which is probably itself a <tt>Fl_Group</tt>). The +children should be sized to stay away from the top or bottom edge of +the <tt>Fl_Tabs</tt>, which is where the tabs are drawn. + +<h4><a name="Fl_Tab.~Fl_Tab">virtual Fl_Tab::~Fl_Tab()</a></h4> + +The destructor <i>also deletes all the children</i>. This allows a +whole tree to be deleted at once, without having to keep a pointer to all +the children in the user code. A kludge has been done so the +<tt>Fl_Tab</tt> and all of it's children can be automatic (local) +variables, but you must declare the <tt>Fl_Tab</tt> <i>first</i>, so +that it is destroyed last. + +<h4><a name="Fl_Tab.value">Fl_Widget* Fl_Tabs::value() const<br> +int Fl_Tabs::value(Fl_Widget*)</a></h4> + +Gets or sets the currently visible widget/tab. + +</body> +</html> diff --git a/documentation/Fl_Tile.gif b/documentation/Fl_Tile.gif Binary files differnew file mode 100644 index 000000000..e96744504 --- /dev/null +++ b/documentation/Fl_Tile.gif diff --git a/documentation/Fl_Tile.html b/documentation/Fl_Tile.html new file mode 100644 index 000000000..ffb85a603 --- /dev/null +++ b/documentation/Fl_Tile.html @@ -0,0 +1,85 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Tile">class Fl_Tile</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Tile</b> + | + +----<a href="#Fl_Pack">Fl_Pack</a>, <a href="#Fl_Scroll">Fl_Scroll</a>, <a href="#Fl_Tabs">Fl_Tabs</a>, <a href="#Fl_Tile">Fl_Tile</a>, <a href="#Fl_Window">Fl_Window</a> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Tile.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Tile</tt> class lets you resize the children by dragging the +border between them: + +<p><img src=Fl_Tile.gif> + +<p><tt>Fl_Tile</tt> allows objects to be resized to zero dimensions. +To prevent this you can use the <tt>resizable()</tt> to limit where +corners can be dragged to. + +<p>Even though objects can be resized to zero sizes, they must +initially have non-zero sizes so the <tt>Fl_Tile</tt> can figure out +their layout. If desired, call <tt>position()</tt> after creating the +children but before displaying the window to set the borders where you +want. + +<p>The "borders" are part of the children, an <tt>Fl_Tile<tt> does not +draw any graphics of it's own. In the above example all the final +children have <tt>FL_DOWN_BOX</tt> types, and the "ridges" you see are +two adjacent <tt>FL_DOWN_BOX</tt>'s drawn next to each other. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Tile.Fl_Tile">Fl_Tile</a> + <li><a href="#Fl_Tile.~Fl_Tile">~Fl_Tile</a> + <li><a href="#Fl_Tile.position">position</a> + <li><a href="#Fl_Tile.resizeable">resizeable</a> +</ul> + +<h4><a name="Fl_Tile.Fl_Tile">Fl_Tile::Fl_Tile(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Tile</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_NO_BOX</tt>. + +<h4><a name="Fl_Tile.~Fl_Tile">virtual Fl_Tile::~Fl_Tile()</a></h4> + +The destructor <i>also deletes all the children</i>. This allows a +whole tree to be deleted at once, without having to keep a pointer to all +the children in the user code. A kludge has been done so the +<tt>Fl_Tile</tt> and all of it's children can be automatic (local) +variables, but you must declare the <tt>Fl_Tile</tt> <i>first</i>, so +that it is destroyed last. + +<h4><a name="Fl_Tile.position">void Fl_Tile::position(from_x, from_y, to_x, to_y)</a></h4> + +Drag the intersection at <tt>from_x,from_y</tt> to <tt>to_x,to_y</tt>. +This redraws all the necessary children. + +<h4><a name="Fl_Tile.resizeable">void Fl_Tile::resizable(Fl_Widget&)</a></h4> + +The "resizable" child widget (which should be invisible) limits where +the border can be dragged to. If you don't set it, it will be possible +to drag the borders right to the edge, and thus resize objects on the +edge to zero width or height. The <tt>resizable()</tt> widget is not +resized by dragging any borders. + +</body> +</html> diff --git a/documentation/Fl_Timer.html b/documentation/Fl_Timer.html new file mode 100644 index 000000000..950ec82a3 --- /dev/null +++ b/documentation/Fl_Timer.html @@ -0,0 +1,81 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Timer">class Fl_Timer</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Timer</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Timer.H> +</pre></ul> + +<h3>Description</h3> + +This is provided only to emulate the Forms Timer widget. It works by +making a timeout callback every 1/5 second. This is wasteful and +inaccurate if you just want something to happen a fixed time in the +future. You should directly call <a +href="#add_timeout"><tt>Fl::add_timeout()</tt></a> instead. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Timer.Fl_Timer">Fl_Timer</a> + <li><a href="#Fl_Timer.~Fl_Timer">~Fl_Timer</a> + <li><a href="#Fl_Timer.direction">direction</a> + <li><a href="#Fl_Timer.suspended">suspended</a> + <li><a href="#Fl_Timer.value">value</a> +</ul> + +<h4><a name="Fl_Timer.Fl_Timer">Fl_Timer::Fl_Timer(uchar type, int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Timer</tt> widget using the given type, position, size, and +label string. The <tt>type</tt> parameter can be any of the following symbolic +constants: + +<ul> + <li><tt>FL_NORMAL_TIMER</tt> - The timer just does the callback + and displays the string "Timer" in the widget. + + <li><tt>FL_VALUE_TIMER</tt> - The timer does the callback and + displays the current timer value in the widget. + + <li><tt>FL_HIDDEN_TIMER</tt> - The timer just does the callback + and does not display anything. +</ul> + +<h4><a name="Fl_Timer.~Fl_Timer">virtual Fl_Timer::~Fl_Timer()</a></h4> + +Destroys the timer and removes the timeout. + +<h4><a name="Fl_Timer.direction">char direction() const<br> +void direction(char d)</a></h4> + +Gets or sets the direction of the timer. If the direction is zero then +the timer will count up, otherwise it will count down from the initial +<tt>value()</tt>. + +<h4><a name="Fl_Timer.suspended">char suspended() const<br> +void suspended(char d)</a></h4> + +Gets or sets whether the timer is suspended. + +<h4><a name="Fl_Timer.value">float value() const<br> +void value(float)</a></h4> + +Gets or sets the current timer value. + +</body> +</html> diff --git a/documentation/Fl_Valuator.html b/documentation/Fl_Valuator.html new file mode 100644 index 000000000..584c91270 --- /dev/null +++ b/documentation/Fl_Valuator.html @@ -0,0 +1,182 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Valuator">class Fl_Valuator</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Widget">Fl_Widget</a> + | + +----<b>Fl_Valuator</b> + | + +----<a href="#Fl_Adjuster">Fl_Adjuster</a>, <a href="#Fl_Counter">Fl_Counter</a>, <a href="#Fl_Dial">Fl_Dial</a>, <a href="#Fl_Roller">Fl_Roller</a>, + <a href="#Fl_Slider">Fl_Slider</a>, <a href="#Fl_Value_Input">Fl_Value_Input</a>, <a href="#Fl_Value_Output">Fl_Value_Output</a>, +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Valuator.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Valuator</tt> class controls a single floating-point value +and provides a consistent interface to set the value, range, and step, +and insures that callbacks are done the same for every object. + +<p>There are probably more of these classes in fltk than any others: + +<p><img src=valuators.gif> + +<p>In the above diagram each box surrounds an actual subclass. These +are further differentiated by setting the <a +href=#Fl_Widget.type"><tt>type()</tt></a> of the widget to the symbolic +value labeling the widget. The ones labelled "0" are the default +versions with a <tt>type(0)<tt>. For consistency the symbol +<tt>FL_VERTICAL</tt> is defined as zero. + +<h3>Methods</h3> + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Valuator.Fl_Valuator">Fl_Valuator</a> + <li><a href="#Fl_Valuator.~Fl_Valuator">~Fl_Valuator</a> + <li><a href="#Fl_Valuator.changed">changed</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Valuator.clamp">clamp</a> + <li><a href="#Fl_Valuator.clear_changed">clear_changed</a> + <li><a href="#Fl_Valuator.format">format</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Valuator.increment">increment</a> + <li><a href="#Fl_Valuator.maximum">maximum</a> + <li><a href="#Fl_Valuator.minimum">minimum</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Valuator.range">range</a> + <li><a href="#Fl_Valuator.round">round</a> + <li><a href="#Fl_Valuator.set_changed">set_changed</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Valuator.step">step</a> + <li><a href="#Fl_Valuator.value">value</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4><a name="Fl_Valuator.Fl_Valuator">Fl_Valuator::Fl_Valuator(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Valuator</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_NO_BOX</tt>. + +<h4><a name="Fl_Valuator.~Fl_Valuator">virtual Fl_Valuator::~Fl_Valuator()</a></h4> + +Destroys the valuator. + +<h4><a name="Fl_Valuator.value">double Fl_Valuator::value() const<br> +int Fl_Valuator::value(double)</a></h4> + +Get or set the current value. The new value is <i>not</i> clamped or +otherwise changed before storing it. Use <tt>clamp()</tt> or +<tt>round()</tt> to modify the value before calling this if you want. +If the new value is different than the current one the object is +redrawn. The initial value is zero. + +<h4><a name="Fl_Valuator.minimum">double Fl_Valuator::minimum() const<br> +void Fl_Valuator::minimum(double)</a></h4> + +Gets or sets the minimum value for the valuator. + +<h4><a name="Fl_Valuator.maximum">double Fl_Valuator::maximum() const<br> +void Fl_Valuator::maximum(double)</a></h4> + +Gets or sets the maximum value for the valuator. + +<h4><a name="Fl_Valuator.range">void Fl_Valuator::range(double min, double max);</a></h4> + +Sets the minimum and maximum values for the valuator. When the user +manipulates the widget, the value is limited to this range. This +clamping is done <i>after</i> rounding to the step value (this makes a +difference if the range is not a multiple of the step). + +<p>The minimum may be greater than the maximum. This has the effect +of "reversing" the object so the larger values are in the opposite +direction. This also switches which end of the filled sliders is +filled. + +<p>Some widgets consider this a "soft" range. This means they will +stop at the range, but if the user releases and grabs the control +again and tries to move it further, it is allowed. + +<p>The range may affect the display. You must <tt>redraw()</tt> the +widget after changing the range. + +<h4><a name="Fl_Valuator.step">double Fl_Valuator::step() const<br> +void Fl_Valuator::step(double)<br> +void Fl_Valuator::step(int A, int B)</a></h4> + +Get or set the step value. As the user moves the mouse the value is +rounded to the nearest multiple of the step value. This is done +<i>before</i> clamping it to the range. For most +objects the default step is zero. + +<p>For precision the step is stored as the ratio of two integers, +A/B. You can set these integers directly. Currently setting a +floating point value sets the nearest A/1 or 1/B value possible. + +<h4><a name="Fl_Valuator.format">int Fl_Valuator::format(char*, double)</a></h4> + +Format the passed value to show enough digits so that for the current +step value. If the step has been set to zero then it does a +<tt>%g</tt> format. The characters are written into the passed buffer. + +<h4><a name="Fl_Valuator.round">double Fl_Valuator::round(double)</a></h4> + +Round the passed value to the nearest step increment. Does nothing if +step is zero. + +<h4><a name="Fl_Valuator.clamp">double Fl_Valuator::clamp(double)</a></h4> + +Clamp the passed value to the valuator range. + +<h4><a name="Fl_Valuator.increment">double Fl_Valuator::increment(double,int n)</a></h4> + +Adds <tt>n</tt> times the step value to the passed value. If step was set to +zero it uses <tt>fabs(maximum() - minimum()) / 100</tt>. + +<h4><a name="Fl_Valuator.changed">int Fl_Widget::changed() const</a></h4> + +This value is true if the user has moved the slider. It is turned +off by <tt>value(x)</tt> and just before doing a callback (the callback can +turn it back on if desired). + +<h4><a name="Fl_Valuator.set_changed">void Fl_Widget::set_changed()</a><h4> + +Sets the <tt>changed()</tt> flag. + +<h4><a name="Fl_Valuator.clear_changed">void Fl_Widget::clear_changed()</a></h4> + +Clears the <tt>changed()</tt> flag. + +</body> +</html> diff --git a/documentation/Fl_Value_Input.gif b/documentation/Fl_Value_Input.gif Binary files differnew file mode 100644 index 000000000..bdc556502 --- /dev/null +++ b/documentation/Fl_Value_Input.gif diff --git a/documentation/Fl_Value_Input.html b/documentation/Fl_Value_Input.html new file mode 100644 index 000000000..597d07f27 --- /dev/null +++ b/documentation/Fl_Value_Input.html @@ -0,0 +1,89 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Value_Input">class Fl_Value_Input</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Valuator">Fl_Valuator</a> + | + +----<b>Fl_Value_Input</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Value_Input.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Value_Input</tt> widget displays a floating point value. +The user can click in the text field and edit it (there is in fact +a hidden <a href="#Fl_Value_Input"><tt>Fl_Value_Input</tt></a> widget with +<tt>type(FL_FLOAT_INPUT)</tt> in there), and when they hit return +or tab the value updates to what they typed and the callback is done. + +<p>If <tt>step()</tt> is not zero, the user can also drag the mouse +across the object and thus slide the value. The left button moves one +<tt>step()</tt> per pixel, the middle by <tt>10 * step()</tt>, and the +left button by <tt>100 * step()</tt>. It is then impossible to select +text by dragging across it, although clicking can still move the +insertion cursor. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Value_Input.Fl_Value_Input">Fl_Value_Input</a> + <li><a href="#Fl_Value_Input.~Fl_Value_Input">~Fl_Value_Input</a> + <li><a href="#Fl_Value_Input.cursor_color">cursor_color</a> + <li><a href="#Fl_Value_Input.soft">soft</a> + <li><a href="#Fl_Value_Input.textcolor">textcolor</a> + <li><a href="#Fl_Value_Input.textfont">textfont</a> + <li><a href="#Fl_Value_Input.textsize">textsize</a> +</ul> + +<h4><a name="Fl_Value_Input.Fl_Value_Input">Fl_Value_Input::Fl_Value_Input(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Value_Input</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_NO_BOX</tt>. + +<h4><a name="Fl_Value_Input.~Fl_Value_Input">virtual Fl_Value_Input::~Fl_Value_Input()</a></h4> + +Destroys the valuator. + +<h4><a name="Fl_Value_Input.cursor_color">Fl_Color Fl_Value_Input::cursor_color() const<br> +void Fl_Value_Input::cursor_color(Fl_Color)</a></h4> + +Get or set the color of the cursor. This is black by default. + +<h4><a name="Fl_Value_Input.soft">uchar Fl_Value_Input::soft() const<br> +void Fl_Value_Input::soft(uchar)</a></h4> + +If "soft" is turned on, the user is allowed to drag the value outside +the range. If they drag the value to one of the ends, let go, then +grab again and continue to drag, they can get to any value. Default +is one. + +<h4><a name="Fl_Value_Input.textcolor">Fl_Color Fl_Value_Input::textcolor() const<br> +void Fl_Value_Input::textcolor(Fl_Color)</a></h4> + +Gets or sets the color of the text in the value box. + +<h4><a name="Fl_Value_Input.textfont">Fl_Font Fl_Value_Input::textfont() const<br> +<br>void Fl_Value_Input::textfont(Fl_Font)</a></h4> + +Gets or sets the typeface of the text in the value box. + +<h4><a name="Fl_Value_Input.textsize">uchar Fl_Value_Input::textsize() const<br> +void Fl_Value_Input::textsize(uchar)</a></h4> + +Gets or sets the size of the text in the value box. + +</body> +</html> diff --git a/documentation/Fl_Value_Output.gif b/documentation/Fl_Value_Output.gif Binary files differnew file mode 100644 index 000000000..5e8c9e97f --- /dev/null +++ b/documentation/Fl_Value_Output.gif diff --git a/documentation/Fl_Value_Output.html b/documentation/Fl_Value_Output.html new file mode 100644 index 000000000..254f7ded0 --- /dev/null +++ b/documentation/Fl_Value_Output.html @@ -0,0 +1,80 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Value_Output">class Fl_Value_Output</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Valuator">Fl_Valuator</a> + | + +----<b>Fl_Value_Output</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Value_Output.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Value_Output</tt> widget displays a floating point value. If +<tt>step()</tt> is not zero, the user can adjust the value by dragging +the mouse left and right. The left button moves one <tt>step()</tt> +per pixel, the middle by <tt>10 * step()</tt>, and the right button by +<tt>100 * step()</tt>. + +<p>This is much lighter-weight than <a +href=#Fl_Value_Input><tt>Fl_Value_Input</tt></a> because it contains no +text editing code or character buffer. + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Value_Output.Fl_Value_Output">Fl_Value_Output</a> + <li><a href="#Fl_Value_Output.~Fl_Value_Output">~Fl_Value_Output</a> + <li><a href="#Fl_Value_Output.soft">soft</a> + <li><a href="#Fl_Value_Output.textcolor">textcolor</a> + <li><a href="#Fl_Value_Output.textfont">textfont</a> + <li><a href="#Fl_Value_Output.textsize">textsize</a> +</ul> + +<h4><a name="Fl_Value_Output.Fl_Value_Output">Fl_Value_Output::Fl_Value_Output(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Value_Output</tt> widget using the given position, size, and +label string. The default boxtype is <tt>FL_NO_BOX</tt>. + +<h4><a name="Fl_Value_Output.~Fl_Value_Output">virtual Fl_Value_Output::~Fl_Value_Output()</a></h4> + +Destroys the valuator. + +<h4><a name="Fl_Value_Output.soft">uchar Fl_Value_Output::soft() const<br> +void Fl_Value_Output::soft(uchar)</a></h4> + +If "soft" is turned on, the user is allowed to drag the value outside +the range. If they drag the value to one of the ends, let go, then +grab again and continue to drag, they can get to any value. Default +is one. + +<h4><a name="Fl_Value_Output.textcolor">Fl_Color Fl_Value_Output::textcolor() const<br> +void Fl_Value_Output::textcolor(Fl_Color)</a></h4> + +Gets or sets the color of the text in the value box. + +<h4><a name="Fl_Value_Output.textfont">Fl_Font Fl_Value_Output::textfont() const<br> +<br>void Fl_Value_Output::textfont(Fl_Font)</a></h4> + +Gets or sets the typeface of the text in the value box. + +<h4><a name="Fl_Value_Output.textsize">uchar Fl_Value_Output::textsize() const<br> +void Fl_Value_Output::textsize(uchar)</a></h4> + +Gets or sets the size of the text in the value box. + +</body> +</html> diff --git a/documentation/Fl_Value_Slider.html b/documentation/Fl_Value_Slider.html new file mode 100644 index 000000000..b8be9ef6d --- /dev/null +++ b/documentation/Fl_Value_Slider.html @@ -0,0 +1,67 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Value_Slider">class Fl_Value_Slider</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Slider">Fl_Slider</a> + | + +----<b>Fl_Value_Slider</b> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Value_Slider.H> +</pre></ul> + +<h3>Description</h3> + +The <tt>Fl_Value_Slider</tt> widget is a <tt>Fl_Slider</tt> widget with +a box displaying the current value. + +<p><img src=value_slider.gif> + +<h3>Methods</h3> + +<ul> + <li><a href="#Fl_Value_Slider.Fl_Value_Slider">Fl_Value_Slider</a> + <li><a href="#Fl_Value_Slider.~Fl_Value_Slider">~Fl_Value_Slider</a> + <li><a href="#Fl_Value_Slider.textcolor">textcolor</a> + <li><a href="#Fl_Value_Slider.textfont">textfont</a> + <li><a href="#Fl_Value_Slider.textsize">textsize</a> +</ul> + +<h4><a name="Fl_Value_Slider.Fl_Value_Slider">Fl_Value_Slider::Fl_Value_Slider(int x, int y, int w, int h, const char *label = 0)</a></h4> + +Creates a new <tt>Fl_Value_Slider</tt> widget using the given position, +size, and label string. The default boxtype is <tt>FL_DOWN_BOX</tt>. + +<h4><a name="Fl_Value_Slider.~Fl_Value_Slider">virtual Fl_Value_Slider::~Fl_Value_Slider()</a></h4> + +Destroys the valuator. + +<h4><a name="Fl_Value_Slider.textcolor">Fl_Color Fl_Value_Slider::textcolor() const<br> +void Fl_Value_Slider::textcolor(Fl_Color)</a></h4> + +Gets or sets the color of the text in the value box. + +<h4><a name="Fl_Value_Slider.textfont">Fl_Font Fl_Value_Slider::textfont() const<br> +<br>void Fl_Value_Slider::textfont(Fl_Font)</a></h4> + +Gets or sets the typeface of the text in the value box. + +<h4><a name="Fl_Value_Slider.textsize">uchar Fl_Value_Slider::textsize() const<br> +void Fl_Value_Slider::textsize(uchar)</a></h4> + +Gets or sets the size of the text in the value box. + +</body> +</html> + diff --git a/documentation/Fl_Widget.html b/documentation/Fl_Widget.html new file mode 100644 index 000000000..5509a8f85 --- /dev/null +++ b/documentation/Fl_Widget.html @@ -0,0 +1,380 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Widget">class Fl_Widget</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<b>Fl_Widget</b> + | + +----<a href="#Fl_Box">Fl_Box</a>, <a href="#Fl_Browser">Fl_Browser</a>, <a href="#Fl_Button">Fl_Button</a>, <a href="#Fl_Chart">Fl_Chart</a>, <a href="#Fl_Clock">Fl_Clock</a>, + <a href="#Fl_Free">Fl_Free</a>, <a href="#Fl_Group">Fl_Group</a>, <a href="#Fl_Input">Fl_Input</a>, <a href="#Fl_Menu_">Fl_Menu_</a>, <a href="#Fl_Positioner">Fl_Positioner</a>, + <a href="#Fl_Timer">Fl_Timer</a>, <a href="#Fl_Valuator">Fl_Valuator</a> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Widget.H> +</pre></ul> + +<h3>Description</h3> + +<tt>Fl_Widget</tt> is the base class for all widgets in FLTK. You can't create +one of these because the constructor is not public. However you can +<a href=#subclassing">subclass</a> it. + +<p>All "property" accessing methods, such as <tt>color()</tt>, +<tt>parent()</tt>, or <tt>argument()</tt> are implemented as trivial inline +functions and thus are as fast and small as accessing fields in a structure. +Unless otherwise noted, the property setting methods such as <tt>color(n)</tt> +or <tt>label(s)</tt> are also trivial inline functions, even if they change +the widget's appearance. It is up to the user code to call <tt>redraw()</tt> +after these. + +<h3>Methods</h3> + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Widget.Fl_Widget">Fl_Widget</a> + <li><a href="#Fl_Widget.~Fl_Widget">~Fl_Widget</a> + <li><a href="#Fl_Widget.activate">activate</a> + <li><a href="#Fl_Widget.active">active</a> + <li><a href="#Fl_Widget.activevisible">activevisible</a> + <li><a href="#Fl_Widget.align">align</a> + <li><a href="#Fl_Widget.argument">argument</a> + <li><a href="#Fl_Widget.box">box</a> + <li><a href="#Fl_Widget.callback">callback</a> + <li><a href="#Fl_Widget.changed">changed</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Widget.clear_changed">clear_changed</a> + <li><a href="#Fl_Widget.color">color</a> + <li><a href="#Fl_Widget.contains">contains</a> + <li><a href="#Fl_Widget.damage">damage</a> + <li><a href="#Fl_Widget.deactivate">deactivate</a> + <li><a href="#Fl_Widget.default_callback">default_callback</a> + <li><a href="#Fl_Widget.do_callback">do_callback</a> + <li><a href="#Fl_Widget.h">h</a> + <li><a href="#Fl_Widget.hide">hide</a> + <li><a href="#Fl_Widget.ih">ih</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Widget.init_size">init_size</a> + <li><a href="#Fl_Widget.inside">inside</a> + <li><a href="#Fl_Widget.iw">iw</a> + <li><a href="#Fl_Widget.ix">ix</a> + <li><a href="#Fl_Widget.iy">iy</a> + <li><a href="#Fl_Widget.label">label</a> + <li><a href="#Fl_Widget.labelcolor">labelcolor</a> + <li><a href="#Fl_Widget.labelfont">labelfont</a> + <li><a href="#Fl_Widget.labelsize">labelsize</a> + <li><a href="#Fl_Widget.labeltype">labeltype</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Widget.parent">parent</a> + <li><a href="#Fl_Widget.position">position</a> + <li><a href="#Fl_Widget.redraw">redraw</a> + <li><a href="#Fl_Widget.resize">resize</a> + <li><a href="#Fl_Widget.selection_color">selection_color</a> + <li><a href="#Fl_Widget.set_changed">set_changed</a> + <li><a href="#Fl_Widget.show">show</a> + <li><a href="#Fl_Widget.size">size</a> + <li><a href="#Fl_Widget.type">type</a> + <li><a href="#Fl_Widget.user_data">user_data</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Widget.visible">visible</a> + <li><a href="#Fl_Widget.w">w</a> + <li><a href="#Fl_Widget.when">when</a> + <li><a href="#Fl_Widget.window">window</a> + <li><a href="#Fl_Widget.x">x</a> + <li><a href="#Fl_Widget.y">y</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4>Fl_Widget::Fl_Widget(int x, int y, int w, int h, const char* label=0);</h4> + +This is the protected constructor for an Fl_Widget, but all derived +widgets have a matching public constructor. It takes a value for +x(), y(), w(), h(), and an optional value for label(). + +<h4>virtual Fl_Widget::~Fl_Widget();</h4> + +Destroying single widgets is not very common. It is your +responsibility to either remove() them from any enclosing group, or to +destroy that group <i>immediately</i> after destroying the children. + +<h4>uchar Fl_Widget::type() const;</h4> + +This value is used for Forms compatability and to simulate RTTI. + +<h4><a name="Fl_Widget.x">short Fl_Widget::x() const</a><br> +<a name="Fl_Widget.y">short Fl_Widget::y() const</a><br> +<a name="Fl_Widget.w">short Fl_Widget::w() const</a><br> +<a name="Fl_Widget.h">short Fl_Widget::h() const</a></h4> + +The position of the upper-left corner of the widget in its enclosing +Fl_Window (<i>not</i> its parent if that is not an Fl_Window), and its +width and height. + +<h4><a name="Fl_Widget.resize">virtual void Fl_Widget::resize(int,int,int,int)</a><br> +<a name="Fl_Widget.position">void Fl_Widget::position(short x,short y)</a><br> +<a name="Fl_Widget.size">void Fl_Widget::size(short w,short h)</a></h4> + +Change the size or position of the widget. This is a virtual function +so the widget may implement it's own handling of resizing. The +default version does <i>not</i> do redraw(), that is the parent +widget's responsibility (this is because the parent may know a faster +way to update the display, such as scrolling from the old position). + +<p><tt>position(x,y)</tt> is a shortcut for <tt>resize(x,y,w(),h())</tt>, +and <tt>size(w,h)</tt> is a shortcut for <tt>resize(x(),y(),w,h)</tt>. + +<h4><a name="Fl_Widget.ix">short Fl_Widget::ix() const</a><br> +<a name="Fl_Widget.iy">short Fl_Widget::iy() const</a><br> +<a name="Fl_Widget.iw">short Fl_Widget::iw() const</a><br> +<a name="Fl_Widget.ih">short Fl_Widget::ih() const</a><br> +<a name="Fl_Widget.init_size">void Fl_Widget::init_size(int,int,int,int)</a></h4> + +The initial size and position of the widget. This is a copy of the +arguments that the constructor was called with. This information is +used by <a href="#Fl_Group"><tt>Fl_Group</tt></a> to calculate new sizes of +the children when they are resized. + +<p><tt>init_size()</tt> calls <tt>resize()</tt> with the passed sizes, +and then replaces the initial size with the new values. If this widget +is a group you will have to init_size all the children as well or +unpredictable results will occur. + +<h4><a name="Fl_Widget.window">Fl_Window* Fl_Widget::window() const;</a></h4> + +Return a pointer to the <a href="#Fl_Window"><tt>Fl_Window</tt></a> +that this widget is in (it will skip any and all parent widgets between +this and the window). Returns NULL if none. Note: for an +<tt>Fl_Window</tt>, this returns it's <i>parent</i> window (if any), +not <i>this</i> window. + +<h4><a name="Fl_Widget.box">Fl_Boxtype Fl_Widget::box() const<br> +void Fl_Widget::box(Fl_Boxtype)</a></h4> + +The <tt>box()</tt> identifies a routine that draws the background of the +widget. See <a href="#BoxTypes">Box Types</a> for the available +types. The default depends on the widget, but is usually <tt>FL_NO_BOX</tt> +or <tt>FL_UP_BOX</tt>. + +<h4><a name="Fl_Widget.color">Fl_Color Fl_Widget::color() const<br> +void Fl_Widget::color(Fl_Color)</a></h4> + +This color is passed to the box routine. Color is an index into an +internal table of rgb colors. For most widgets this defaults to +<tt>FL_GRAY</tt>. See the <a href="#Enumerations">enumeration list</a> +for predefined colors. Use +<a href="#set_color"><tt>Fl::set_color()</tt></a> to redefine colors. + +<h4><a name="Fl_Widget.selection_color">Fl_Color Fl_Widget::selection_color() const<BR> +void Fl_Widget::selection_color(Fl_Color)</a><br> +void Fl_Widget::color(Fl_Color, Fl_Color)</h4> + +For Forms compatibility a second color is defined. This is usually +used to color the widget when it is selected, although some widgets +use this color for other purposes. You can set both colors at once +with <tt>color(a,b)</tt>. + +<h4><a name="Fl_Widget.label">const char* Fl_Widget::label() const<br> +void Fl_Widget::label(const char*)</a></h4> + +The label is printed somewhere on the widget or next to it. The +string is <i>not</i> copied, the passed pointer is stored unchanged in +the widget. + +<h4><a name="Fl_Widget.labeltype">void Fl_Widget::label(Fl_Labeltype, const char*)<br> +uchar Fl_Widget::labeltype() const<br> +void Fl_Widget::labeltype(Fl_Labeltype)</a></h4> + +A <a href=#LabelTypes><tt>labeltype</tt></a> identifies a routine that +draws the label of the widget. This can be used for special effects +such as emboss, or to use the <tt>label()</tt> pointer as another form +of data such as a bitmap. The value <tt>FL_NORMAL_LABEL</tt> prints +the label as text. + +<h4><a name="Fl_Widget.align">Fl_Align Fl_Widget::align() const<br> +void Fl_Widget::align(Fl_Align)</a></h4> + +How the label is printed next to or inside the widget. The default +value is <tt>FL_ALIGN_CENTER</tt>, which centers the label. The value +can be any of these constants or'd together: + +<tt><ul> +<li>FL_ALIGN_CENTER +<li>FL_ALIGN_TOP +<li>FL_ALIGN_BOTTOM +<li>FL_ALIGN_LEFT +<li>FL_ALIGN_RIGHT +<li>FL_ALIGN_INSIDE +<li>FL_ALIGN_CLIP +<li>FL_ALIGN_WRAP +</ul></tt> + +<h4><a name="Fl_Widget.labelcolor">Fl_Color Fl_Widget::labelcolor() const<br> +void Fl_Widget::labelcolor(Fl_Color)</a></h4> + +This color is passed to the labeltype routine, and is typically the +color of the label text. This defaults to <tt>FL_BLACK</tt>. + +<h4><a name="Fl_Widget.labelfont">Fl_Font Fl_Widget::labelfont() const<br> +void Fl_Widget::labelfont(Fl_Font)</a></h4> + +Fonts are identified by small 8-bit indexes into a table. See the +<a href="#Enumerations">enumeration list</a> for predefined typefaces. The +default value uses a Helvetica typeface (Arial for Microsoft® +Windows®). The function <a href="#set_font"><tt>Fl::set_font() +</tt></a> can define new typefaces. + +<h4><a name="Fl_Widget.labelsize">uchar Fl_Widget::labelsize() const<br> +void Fl_Widget::labelsize(uchar)</a></h4> + +Fonts are further identified by a point size. The default is 14. + +<h4><a name="Fl_Widget.callback">typedef void (Fl_Callback)(Fl_Widget*, void*)<br> +Fl_Callback* Fl_Widget::callback() const<br> +void Fl_Widget::callback(Fl_Callback*, void* = 0)</a></h4> + +Each widget has a single callback. You can set it or examine it with +these methods. + +<h4><a name="Fl_Widget.user_data">void* Fl_Widget::user_data() const<br> +void Fl_Widget::user_data(void*)</a></h4> + +You can also just change the <tt>void *</tt> second argument to the callback +with the <tt>user_data</tt> methods. + +<h4><a name="Fl_Widget.argument">void Fl_Widget::callback(void (*)(Fl_Widget*, long), long = 0)<br> +long Fl_Widget::argument() const<br> +void Fl_Widget::argument(long)</a></h4> + +For convenience you can also define the callback as taking a long +argument. This is implemented by casting this to a +<tt>Fl_Callback</tt> and casting the <tt>long</tt> to a <tt>void *</tt> +and may not be portable to some machines. + +<h4>void Fl_Widget::callback(void (*)(Fl_Widget*))</h4> + +For convenience you can also define the callback as taking only one +argument. This is implemented by casting this to a +<tt>Fl_Callback</tt> and may not be portable to some machines. + +<h4><a name="Fl_Widget.do_callback">void Fl_Widget::do_callback()<br> +void Fl_Widget::do_callback(Fl_Widget*, void* = 0)<br> +void Fl_Widget::do_callback(Fl_Widget*, long)</a></h4> + +You can cause a widget to do its callback at any time, and even pass +arbitrary arguments. + +<h4><a name="Fl_Widget.changed">int Fl_Widget::changed() const</a><br> +<a name="Fl_Widget.set_changed">void Fl_Widget::set_changed()</a><br> +<a name="Fl_Widget.clear_changed">void Fl_Widget::clear_changed()</a></h4> + +<tt>Fl_Widget::changed()</tt> is a flag that is turned on when the user +changes the value stored in the widget. This is only used by +subclasses of <tt>Fl_Widget</tt> that store values, but is in the base +class so it is easier to scan all the widgets in a panel and +<tt>do_callback()</tt> on the changed ones in response to an "OK" +button. + +<p>Most widgets turn this flag off when they do the callback, and when +the program sets the stored value. + +<h4><a name="Fl_Widget.when">Fl_When Fl_Widget::when() const<br> +void Fl_Widget::when(Fl_When)</a></h4> + +<tt>Fl_Widget::when()</tt> is a set of bitflags used by subclasses of +<tt>Fl_Widget</tt> to decide when to do the callback. If the value is +zero then the callback is never done. Other values are described in +the individual widgets. This field is in the base class so that you +can scan a panel and <tt>do_callback()</tt> on all the ones that don't +do their own callbacks in response to an "OK" button. + +<h4><a name="Fl_Widget.default_callback">static void Fl_Widget::default_callback(Fl_Widget*, void*)</a></h4> + +The default callback, which puts a pointer to the widget on the queue +returned by <a href="#readqueue"><tt>Fl::readqueue()</tt></a>. You +may want to call this from your own callback. + +<h4><a name="Fl_Widget.visible">int Fl_Widget::visible() const</a><br> +<a name="Fl_Widget.show">void Fl_Widget::show()</a><br> +<a name="Fl_Widget.hide">void Fl_Widget::hide()</a></h4> + +An invisible widget never gets redrawn and does not get events. An +widget is really visible if <tt>visible()</tt> is true on it <i>and all +it's parents</i>. Changing it will send <tt>FL_SHOW</tt> or +<tt>FL_HIDE</tt> events to the widget. <i>Do not change it if the +parent is not visible, as this will send false <tt>FL_SHOW</tt> or +<tt>FL_HIDE</tt> events to the widget</i>. <tt>redraw()</tt> is called +if necessary on this or the parent. + +<h4><a name="Fl_Widget.active">int Fl_Widget::active() const</a><br> +<a name="Fl_Widget.activate">void Fl_Widget::activate()</a><br> +<a name="Fl_Widget.deactivate">void Fl_Widget::deactivate()</a><br></h4> + +<tt>Fl_Widget::active()</tt> returns whether the widget is active. An +inactive widget does not get any events, but it does get redrawn. A +widget is active if <tt>active()</tt> is true on it <i>and all it's +parents</i>. Changing this value will send <tt>FL_ACTIVATE</tt> or +<tt>FL_DEACTIVATE</tt> to the widget. <i>Do not change it if the +parent is not active, as this will send false <tt>FL_ACTIVATE</tt> or +<tt>FL_DEACTIVATE</tt> events to the widget</i>. + +<p>Currently you cannot deactivate <tt>Fl_Window</tt> widgets. + +<h4><a name="Fl_Widget.activevisible">int Fl_Widget::activevisible() const</a></h4> + +This is the same as <tt>active() && visible()</tt> but is faster. + +<h4><a name="Fl_Widget.redraw">void Fl_Widget::redraw()</a></h4> + +Mark the widget as needing its <tt>draw()</tt> routine called. + +<h4><a name="Fl_Widget.damage">uchar Fl_Widget::damage() const</a></h4> + +Non-zero if <tt>draw()</tt> needs to be called. Actually this is a bit +field that the widget subclass can use to figure out what parts to +draw. + +<h4><a name="Fl_Widget.parent">Fl_Widget *Fl_Widget::parent() const</a></h4> + +Returns a pointer to the parent widget. Usually this is a +<a href="#Fl_Group"><tt>Fl_Group</tt></a> or +<a href="Fl_Window><tt>Fl_Window</tt></a>. Returns <tt>NULL</tt> if none. + +<h4><a name="Fl_Widget.contains">int Fl_Widget::contains(Fl_Widget* b) const</a></h4> + +Returns true if <tt>b</tt> is a child of this widget, or is equal to +this widget. Returns false if <tt>b</tt> is <tt>NULL</tt>. + +<h4><a name="Fl_Widget.inside">int Fl_Widget::inside(const Fl_Widget* a) const</a></h4> + +Returns true if this is a child of <tt>a</tt>, or is equal to <tt>a</tt>. +Returns false if <tt>a</tt> is <tt>NULL</tt>. + +</body> +</html> diff --git a/documentation/Fl_Window.html b/documentation/Fl_Window.html new file mode 100644 index 000000000..c087e10f0 --- /dev/null +++ b/documentation/Fl_Window.html @@ -0,0 +1,341 @@ +<html> +<body> + +<hr break> + +<h2><a name="Fl_Window">class Fl_Window</a></h2> + +<hr> + +<h3>Class Hierarchy</h3> + +<ul><pre> +<a href="#Fl_Group">Fl_Group</a> + | + +----<b>Fl_Window</b> + | + +----<a href="#Fl_Double_Window">Fl_Double_Window</a>, <a href="#Fl_Gl_Window">Fl_Gl_Window</a>, + <a href="#Fl_Overlay_Window">Fl_Overlay_Window</a>, <a href="#Fl_Single_Window">Fl_Single_Window</a> +</pre></ul> + +<h3>Include Files</h3> + +<ul><pre> +#include <FL/Fl_Window.H> +</pre></ul> + +<h3>Description</h3> + +This widget produces an actual window. This can either be a main +window, with a border and title and all the window management +controls, or a "subwindow" inside a window. This is controlled +by whether or not the window has a <tt>parent()</tt>. + +<p>Once you create a window, you usually add children +<tt>Fl_Widget</tt>'s to it by using <tt>window->add(child)</tt> for +each new widget. See <a href="#Fl_Group"><tt>Fl_Group</tt></a> for +more information on how to add and remove children. + +<p>There are several subclasses of <tt>Fl_Window</tt> that provide +double-buffering, overlay, menu, and OpenGL support. + +<p>The window's callback is done if the user tries to close a window +using the window manager and <a href="#modal"><tt>Fl::modal()</tt></a> +is zero or equal to the window. <tt>Fl_Window</tt> has a default +callback that calls <tt>Fl_Window::hide()</tt> and calls +<tt>exit(0)</tt> if this is the last top-level window. + +<h3>Methods</h3> + +<center> +<table width=90%> +<tr> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Window.Fl_Window">Fl_Window</a> + <li><a href="#Fl_Window.~Fl_Window">~Fl_Window</a> + <li><a href="#Fl_Window.border">border</a> + <li><a href="#Fl_Window.clear_border">clear_border</a> + <li><a href="#Fl_Window.current">current</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Window.first_window">first_window</a> + <li><a href="#Fl_Window.free_position">free_position</a> + <li><a href="#Fl_Window.fullscreen">fullscreen</a> + <li><a href="#Fl_Window.fullscreen_off">fullscreen_off</a> + <li><a href="#Fl_Window.hide">hide</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Window.hotspot">hotspot</a> + <li><a href="#Fl_Window.iconize">iconize</a> + <li><a href="#Fl_Window.iconlabel">iconlabel</a> + <li><a href="#Fl_Window.label">label</a> + <li><a href="#Fl_Window.make_current">make_current</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Window.modal">modal</a> + <li><a href="#Fl_Window.next_window">next_window</a> + <li><a href="#Fl_Window.non_modal">non_modal</a> + <li><a href="#Fl_Window.resize">resize</a> + <li><a href="#Fl_Window.set_modal">set_modal</a> +</ul> +</td> +<td align=left valign=top> +<ul> + <li><a href="#Fl_Window.set_non_modal">set_non_modal</a> + <li><a href="#Fl_Window.show">show</a> + <li><a href="#Fl_Window.shown">shown</a> + <li><a href="#Fl_Window.size_range">size_range</a> + <li><a href="#Fl_Window.xclass">xclass</a> +</ul> +</td> +</tr> +</table> +</center> + +<h4><a name="Fl_Window.Fl_Window">Fl_Window::Fl_Window(int x, int y, int w, int h, const char *title = 0)<br> +Fl_Window::Fl_Window(int w, int h, const char *title = 0)</a></h4> + +The first constructor takes 4 int arguments to create the window with +a preset position and size. The second constructor with 2 arguments +will create the window with a preset size, but the window manager +will choose the position according to it's own whims. + +<p><tt>Fl_Widget::box()</tt> is set to <tt>FL_FLAT_BOX</tt>. If you +plan to completely fill the window with children widgets you should +change this to <tt>FL_NO_BOX</tt>. If you turn the window border off +you may want to change this to <tt>FL_UP_BOX</tt>. + +<h4><a name="Fl_Window.~Fl_Window">virtual Fl_Window::~Fl_Window()</a></h4> + +The destructor <i>also deletes all the children</i>. This allows a +whole tree to be deleted at once, without having to keep a pointer to all +the children in the user code. A kludge has been done so the +<tt>Fl_Window</tt> and all of it's children can be automatic (local) +variables, but you must declare the <tt>Fl_Window</tt> <i>first</i>, so +that it is destroyed last. + +<h4><a name="Fl_Window.size_range">void Fl_Window::size_range(int minw, int minh, int maxw=0, int maxh=0, int dw=0, int dh=0, int aspect=0)</a></h4> + +Set the allowable range the user can resize this window to. This only +works for top-level windows. + +<ul> + <li><tt>minw</tt> and <tt>minh</tt> are the smallest the window + can be. + + <li><tt>maxw</tt> and <tt>maxh</tt> are the largest the window + can be. If either is <i>equal</i> to the minimum then you + cannot resize in that direction. If either is zero + then FLTK picks a maximum size in that direction such that the + window will fill the screen. + + <li><tt>dw</tt> and <tt>dh</tt> are size increments. The + window will be constrained to widths of <tt>minw + N * dw</tt>, + where <tt>N</tt> is any non-negative integer. If these are + less or equal to 1 they are ignored. + + <li><tt>aspect</tt> is a flag that indicates that the window should + preserve it's aspect ratio. This only works if both the maximum and + minimum have the same aspect ratio. +</ul> + +If this function is not called, FLTK tries to figure out the range +from the setting of <a href="#Fl_Group.resizable"><tt>resizeable()</tt></a>: + +<ul> + <li>If <tt>resizeable()</tt> is <tt>NULL</tt> (this is the + default) then the window cannot be resized and the resize + border and max-size control will not be displayed for the + window. + + <li>If either dimension of <tt>resizeable()</tt> is less than + 100, then that is considered the minimum size. Otherwise the + <tt>resizeable()</tt> has a minimum size of 100. + + <li>If either dimension of <tt>resizeable()</tt> is zero, then + that is also the maximum size (so the window cannot resize in + that direction). +</ul> + +It is undefined what happens if the current size does not fit in +the constraints passed to <tt>size_range()</tt>. + +<h4><a name="Fl_Window.show">virtual void Fl_Window::show()<br> +int Fl_Window::show(int argc, char **argv, int i)<br> +void Fl_Window::show(int argc, char **argv)</a></h4> + +Put the window on the screen. Usually this has the side effect of +opening the display. The second two forms are used for top-level +windows and allow standard arguments to be parsed from the +command-line. + +<p>If the window is already shown then it is restored and raised to the +top. This is really convenient because your program can call +<tt>show()</tt> at any time, even if the window is already up. It also +means that <tt>show()</tt> serves the purpose of <tt>raise()</tt> in +other toolkits. + +<h4><a name="Fl_Window.hide">virtual void Fl_Window::hide()</a></h4> + +Remove the window from the screen. If the window is already hidden or +has not been shown then this does nothing (and is harmless). <i>Under the +X Window System this actually destroys the xid</i>. + +<h4><a name="Fl_Window.shown">int Fl_Window::shown() const</a></h4> + +Returns non-zero if <tt>show()</tt> has been called (but not <tt>hide()</tt>). +You can tell if a window is iconified with <tt>(w->shown() && !w->visible())</tt>. + +<h4><a name="Fl_Window.iconize">void Fl_Window::iconize()</a></h4> + +Iconifies the window. If you call this when <tt>shown()</tt> is false +it will <tt>show()</tt> it as an icon. If the window is already +iconified this does nothing. + +<p>Call <tt>show()</tt> to restore the window. + +<p>When a window is iconified/restored (either by these calls or by the +user) the <tt>handle()</tt> method is called with <tt>FL_HIDE</tt> and +<tt>FL_SHOW</tt> events and <tt>visible()</tt> is turned on and off. + +<p>There is no way to control what is drawn in the icon except with the +string passed to <tt>Fl_Window::xclass()</tt>. You should not rely on +window managers displaying the icons. + +<h4><a name="Fl_Window.first_window">Fl_Window *Fl::first_window()</a></h4> + +Returns the first <tt>shown()</tt> window in the widget hierarchy. +If no windows are displayed <tt>first_window</tt> returns <tt>NULL</tt>. + +<h4><a name="Fl_Window.next_window">Fl_Window *Fl::next_window(const Fl_Window*)</a></h4> + +Returns the next <tt>shown()</tt> window in the hierarchy. You can use this +call to iterate through all the windows that are shown(). + +<h4><a name="Fl_Window.resize">void Fl_Window::resize(int,int,int,int)</a></h4> + +Change the size and position of the window. If <tt>shown()</tt> is +true, these changes are communicated to the window server (which may +refuse that size and cause a further resize). If <tt>shown()</tt> is +false, the size and position are used when <tt>show()</tt> is called. +See <a href="#Fl_Group"><tt>Fl_Group</tt></a> for the effect of +resizing on the child widgets. + +<p>You can also call the <tt>Fl_Widget</tt> methods <tt>size(x,y)</tt> +and <tt>position(w,h)</tt>, which are inline wrappers for this virtual +function. + +<h4><a name="Fl_Window.free_position">void Fl_Window::free_position()</a></h4> + +Undoes the effect of a previous <tt>resize()</tt> or <tt>show()</tt> so +that the next time <tt>show()</tt> is called the window manager is free +to position the window. + +<h4><a name="Fl_Window.hotspot">void Fl_Window::hotspot(int x, int y, int offscreen = 0)<br> +void Fl_Window::hotspot(const Fl_Widget*, int offscreen = 0)<br> +void Fl_Window::hotspot(const Fl_Widget& p, int offscreen = 0)</a></h4> + +<tt>position()</tt> the window so that the mouse is pointing at the +given position, or at the center of the given widget, which may be the +window itself. If the optional <tt>offscreen</tt> parameter is +non-zero, then the window is allowed to extend off the screen (this +does not work with some X window managers). + +<h4><a name="Fl_Window.fullscreen">void Fl_Window::fullscreen()</a></h4> + +Makes the window completely fill the screen, without any window manager +border visible. You must use <tt>fullscreen_off()</tt> to undo this. +This may not work with all window managers. + +<h4><a name="Fl_Window.fullscreen_off">int Fl_Window::fullscreen_off(int x, int y, int w, int h)</a></h4> + +Turns off any side effects of <tt>fullscreen()</tt> and does +<tt>resize(x,y,w,h)</tt>. + +<h4><a name="Fl_Window.border">int Fl_Window::border(int)<br> +uchar Fl_Window::border() const</a></h4> + +Gets or sets whether or not the window manager border is around the +window. The default value is true. <tt>border(n)</tt> can be used to +turn the border on and off, and returns non-zero if the value has been +changed. <i>Under most X window managers this does not work after +<tt>show()</tt> has been called, although SGI's 4DWM does work.</i> + +<h4><a name="Fl_Window.clear_border">void Fl_Window::clear_border()</a></h4> + +<tt>clear_border()</tt> is a fast inline function to turn the border +off. It only works before <tt>show()</tt> is called. + +<h4><a name="Fl_Window.set_modal">void Fl_Window::set_modal()</a></h4> + +A "modal" window, when <tt>shown()</tt>, will prevent any events from +being delivered to other windows in the same program, and will also +remain on top of the other windows (if the X window manager supports +the "transient for" property). Several modal windows may be shown at +once, in which case only the last one shown gets events. You can see +which window (if any) is modal by calling <a +href="#modal"><tt>Fl::modal()</tt></a>. + +<h4><a name="Fl_Window.modal">uchar Fl_Window::modal() const</a></h4> + +Returns true if this window is modal. + +<h4><a name="Fl_Window.set_non_modal">void Fl_Window::set_non_modal()</a></h4> + +A "non-modal" window (terminology borrowed from Microsoft Windows) acts +like a <tt>modal()</tt> one in that it remains on top, but it has no +effect on event delivery. There are <i>three</i> states for a window: +modal, non-modal, and normal. + +<h4><a name="Fl_Window.non_modal">uchar Fl_Window::non_modal() const</a></h4> + +Returns true if this window is modal or non-modal. + +<h4><a name="Fl_Window.label">void Fl_Window::label(const char*)<br> +const char* Fl_Window::label() const</a></h4> + +Gets or sets the window title bar label. + +<h4><a name="Fl_Window.iconlabel">void Fl_Window::iconlabel(const char*)<br> +const char* Fl_Window::iconlabel() const</a></h4> + +Gets or sets the icon label. + +<h4><a name="Fl_Window.xclass">void Fl_Window::xclass(const char*)<br> +const char* Fl_Window::xclass() const</a></h4> + +A string used to tell the system what type of window this is. +Mostly this identifies the picture to draw in the icon. <i>Under X, +this is turned into a <tt>XA_WM_CLASS</tt> pair by truncating at the +first non-alphanumeric character and capitalizing the first character, +and the second one if the first is 'x'. Thus "foo" turns into "foo, +Foo", and "xprog.1" turns into "xprog, XProg".</i> This only works if +called <i>before</i> calling <tt>show()</tt>. + +<p>This method has no effect under Microsoft Windows. + +<h4><a name="Fl_Window.make_current">void Fl_Window::make_current()</a></h4> + +<tt>make_current()</tt> sets things up so that the drawing functions in +<a href="#Drawing"><tt><FL/fl_draw.H></tt></a> will go into this +window. This is useful for incremental update of windows, such as in an +idle callback, which will make your program behave much better if it +draws a slow graphic. <b>Danger: incremental update is very hard to +debug and maintain!</b> + +<p>This method only works for the <tt>Fl_Window</tt> and <tt>Fl_Gl_Window</tt> +classes. + +<h4><a name="Fl_Window.current">static Fl_Window* Fl_Window::current()</a></h4> + +Returns the last window that was made current. + +</body> +</html> diff --git a/documentation/adjuster1.gif b/documentation/adjuster1.gif Binary files differnew file mode 100644 index 000000000..9425669cf --- /dev/null +++ b/documentation/adjuster1.gif diff --git a/documentation/ask.C.gif b/documentation/ask.C.gif Binary files differnew file mode 100644 index 000000000..d4ae1a40a --- /dev/null +++ b/documentation/ask.C.gif diff --git a/documentation/basics.html b/documentation/basics.html new file mode 100644 index 000000000..62e74d7e0 --- /dev/null +++ b/documentation/basics.html @@ -0,0 +1,211 @@ +<HTML> +<BODY> + +<H1 ALIGN=RIGHT>2 - FLTK Basics</H1> + +This chapter will teach you the basics of compiling programs that use +FLTK. + +<H2>Naming</H2> + +All public symbols in FLTK start with the characters 'F' and 'L': + +<ul> + + <li>Functions are either <tt>Fl::foo()</tt> or <tt>fl_foo()</tt>. + + <li>Class and type names are capitalized: <tt>Fl_Foo</tt>. + + <li><a href=#Enumerations>Constants and enumerations</a> are + uppercase: <tt>FL_FOO</tt>. + + <li>All header files start with <tt><FL/...></tt>. + +</ul> + +<H2>Header Files</H2> + +The proper way to include FLTK header files is: + +<ul><pre> +#include <FL/Fl_xyz.H> +</pre></ul> + +Microsoft Windows developers please note: case *is* significant +under other operating systems, and the C standard uses the forward +slash (/) to separate directories. The following <tt>#include</tt> +directives are *not* recommended for portability reasons: + +<ul><pre> +#include <fl\fl_xyz.h> +#include <fl/fl_xyz.h> +#include <FL\Fl_xyz.H> +</pre></ul> + +<H2>Compiling Programs with Standard Compilers</H2> + +Under UNIX (and under Microsoft Windows when using the GNU development tools) +you will probably need to tell the compiler where to find the header files. +This is usually done using the <tt>-I</tt> option: + +<ul><pre> +CC -I/usr/local/include ... +gcc -I/usr/local/include ... +</pre></ul> + +Similarly, when linking your application you will need to tell the compiler +to use the FLTK library: + +<ul><pre> +CC ... -L/usr/local/lib -lfltk -lXext -lX11 -lm +gcc ... -L/usr/local/lib -lfltk -lXext -lX11 -lm +</pre></ul> + +<H2>Compiling Programs with Microsoft Visual C++</H2> + +In Visual C++ you will need to tell the compiler where to find the FLTK +header files. This can be done by selecting "Settings" from the +"Project" menu and then changing the "Preprocessor" settings under the +"C/C++" tab. Similarly, you will need to add the FLTK library to the +"Link" settings. + +<p>You can build your Microsoft Windows applications as Console or +WIN32 applications. If you want to use the standard C <tt>main()</tt> +function as the entry point, enter the name <tt>mainCRTStartup</tt> in +the "Entry-point symbol" field in the "Output" settings under the +"Link" tab. + +<p><i>Note: The Visual C++ optimizer is known to cause problems with +many programs. We only recommend using the "Favor Small Code" +optimization setting. + +<H2>Writing Your First FLTK Program</H2> + +All programs must include the file <tt><FL/Fl.H></tt>. In +addition the program must include a header file for each FLTK class it +uses. Listing 1 shows a simple "Hello, World!" program that uses +FLTK to display the window. + +<ul> +<i>Listing 1 - "hello.cxx"</i> +<br> +<pre> +#include <FL/Fl.H> +#include <FL/Fl_Window.H> +#include <FL/Fl_Box.H> + +int main(int argc, char **argv) { + Fl_Window *window = new Fl_Window(300,180); + Fl_Box *box = new Fl_Box(FL_UP_BOX,20,40,260,100,"Hello, World!"); + box->labelsize(36); + box->labelfont(FL_BOLD+FL_ITALIC); + box->labeltype(FL_SHADOW_LABEL); + window->end(); + window->show(argc, argv); + return Fl::run(); +} +</pre></ul> + +After including the required header files, the program then creates a +window: + +<ul><pre> +Fl_Window *window = new <a href="#Fl_Window">Fl_Window</a>(300,180); +</pre></ul> + +and a box with the "Hello, World!" string in it: + +<ul><pre> +Fl_Box *box = new <a href="#Fl_Box">Fl_Box</a>(FL_UP_BOX,20,40,260,100,"Hello, World!"); +</pre></ul> + +Next, we set the size, font, and style of the label: + +<ul><pre> +box-><a href="#Fl_Widget.labelsize">labelsize</a>(36); +box-><a href="#Fl_Widget.labelfont">labelfont</a>(FL_BOLD+FL_ITALIC); +box-><a href="#Fl_Widget.labeltype">labeltype</a>(FL_SHADOW_LABEL); +</pre></ul> + +Finally, we show the window and enter the FLTK event loop: + +<ul><pre> +window-><a href="#Fl_Group.end">end</a>(); +window-><a href="#Fl_Window.show">show</a>(argc, argv); +return <a href="#run">Fl::run</a>(); +</pre></ul> + +The resulting program will display the window below. You can quit +the program by closing the window or pressing the ESCape key. + +<center><img src=hello.C.gif></center> + +<H3>Creating the Widgets</H3> + +The widgets are created using the C++ <tt>new</tt> operator; the arguments +to the constructors are usually one of the following: + +<ul><pre> +Fl_Widget(boxtype, x, y, width, height) +Fl_Widget(x, y, width, height) +Fl_Widget(width, height) +</pre></ul> + +The <tt>boxtype</tt> value is the style of the box that is drawn around +the widget. Usually this is <tt>FL_NO_BOX</tt>, which means that no +box is drawn. In our "Hello, World!" example we use <tt>FL_UP_BOX</tt>, +which means that a raised button border will be drawn around the +widget. You can learn more about boxtypes in <a href="#common">Chapter +3</a>. + +<p>The <tt>x</tt> and <tt>y</tt> parameters determine where the widget +or window is placed on the screen. In FLTK the top left corner of the +window or screen is the origin (i.e. x = 0, y = 0) and the units are in +pixels. + +<p>The <tt>width</tt> and <tt>height</tt> parameters determine the size +of the widget or window in pixels. The maximum widget size is typically +governed by the underlying window system or hardware. + +<H3>Labels</H3> + +All widgets support labels. In the case of window widgets, the label +is used for the label in the title bar. Our example program calls the +<a href="#Fl_Widget.labelfont"><tt>labelfont</tt></a>, +<a href="#Fl_Widget.labelsize"><tt>labelsize</tt></a>, and +<a href="#Fl_Widget.labeltype"><tt>labeltype</tt></a> methods. + +<p>The <tt>labelfont</tt> method sets the typeface and style that is +used for the label, which for this example we are using +<tt>FL_BOLD</tt> and <tt>FL_ITALIC</tt>. You can also specify typefaces +directly. + +<p>The <tt>labelsize</tt> method sets the height of the font in pixels. + +<p>The <tt>labeltype</tt> method sets the type of label. FLTK supports +normal, embossed, shadowed, symbol, and image labels. + +<p>A complete list of all label options can be found in <a href="#common"> +Chapter 3</a>. + +<H3>Showing the Window</H3> + +The <tt>show()</tt> method shows the widget or window. For windows you can +also provide the command-line arguments to allow users to customize the +appearance, size, and position of your windows. + +<H3>The Main Event Loop</H3> + +FLTK provides the <a href="#run"><tt>Fl:run()</tt></a> method to enter +a standard event processing loop. This is equivalent to the following +code: + +<ul><pre> +while (Fl::wait()); +</pre></ul> + +<tt>Fl::run()</tt> does not return until all of the windows under FLTK control +are closed (either by the user or your program). + +</BODY> +</HTML> diff --git a/documentation/bglogo.gif b/documentation/bglogo.gif Binary files differnew file mode 100644 index 000000000..748f71395 --- /dev/null +++ b/documentation/bglogo.gif diff --git a/documentation/boxtypes.gif b/documentation/boxtypes.gif Binary files differnew file mode 100644 index 000000000..ff4d3a473 --- /dev/null +++ b/documentation/boxtypes.gif diff --git a/documentation/button.C.gif b/documentation/button.C.gif Binary files differnew file mode 100644 index 000000000..bbfda3eee --- /dev/null +++ b/documentation/button.C.gif diff --git a/documentation/buttons.gif b/documentation/buttons.gif Binary files differnew file mode 100644 index 000000000..6b405f400 --- /dev/null +++ b/documentation/buttons.gif diff --git a/documentation/charts.gif b/documentation/charts.gif Binary files differnew file mode 100644 index 000000000..f204e14f4 --- /dev/null +++ b/documentation/charts.gif diff --git a/documentation/choice.gif b/documentation/choice.gif Binary files differnew file mode 100644 index 000000000..83247dffd --- /dev/null +++ b/documentation/choice.gif diff --git a/documentation/clock.gif b/documentation/clock.gif Binary files differnew file mode 100644 index 000000000..41e8f1967 --- /dev/null +++ b/documentation/clock.gif diff --git a/documentation/common.html b/documentation/common.html new file mode 100644 index 000000000..2f75ea98b --- /dev/null +++ b/documentation/common.html @@ -0,0 +1,389 @@ +<HTML> +<BODY> + +<H1 ALIGN=RIGHT>3 - Common Widgets and Attributes</H1> + +This chapter describes many of the widgets that are provided with FLTK and covers how +to query and set the standard attributes. + +<H2>Buttons</H2> + +FLTK provides many types of buttons: + +<ul> + <li><tt>Fl_Button</tt> - A standard push button. + <li><tt>Fl_Check_Button</tt> - A button with a check box. + <li><tt>Fl_Light_Button</tt> - A push button with a light. + <li><tt>Fl_Repeat_Button</tt> - A push button that repeats when held. + <li><tt>Fl_Return_Button</tt> - A push button that is activated by the Enter key. + <li><tt>Fl_Round_Button</tt> - A button with a check circle. +</ul> + +For all of these buttons you just need to include the corresponding +<tt><FL/Fl_xyz_Button.H></tt> header file. The constructor takes the +bounding box of the button and optionally a label string: + +<ul><pre> +Fl_Button *button = new Fl_Button(x, y, width, height, "label"); +Fl_Light_Button *lbutton = new Fl_Light_Button(x, y, width, height); +Fl_Round_Button *rbutton = new Fl_Round_Button(x, y, width, height, "label"); +</pre></ul> + +Each button has an associated <a href="#Fl_Button.type"><tt>type()</tt></a> +which allows it to behave as a push button, toggle button, or radio button: + +<ul><pre> +button->type(0); +lbutton->type(FL_TOGGLE_BUTTON); +rbutton->type(FL_RADIO_BUTTON); +</pre></ul> + +For toggle and radio buttons, the <a href="#Fl_Button.value"><tt>value()</tt></a> +method returns the current button state (0 = off, 1 = on). The +<a href="#Fl_Widget.set"><tt>set()</tt></a> and +<a href="#Fl_Widget.clear"><tt>clear()</tt></a> methods can be used on toggle +buttons to turn a toggle button on or off, respectively. Radio buttons can +be turned on with the <a href="#Fl_Widget.setonly"><tt>setonly()</tt></a> +method; this will also turn off other radio buttons in the current group. + +<H2>Text</H2> + +FLTK provides several text widgets for displaying and receiving text: + +<ul> + <li><tt>Fl_Input</tt> - A standard one-line text input field. + <li><tt>Fl_Output</tt> - A standard one-line text output field. + <li><tt>Fl_Multiline_Input</tt> - A standard multi-line text input field. + <li><tt>Fl_Multiline_Output</tt> - A standard multi-line text output field. +</ul> + +The <tt>Fl_Output</tt> and <tt>Fl_Multiline_Output</tt> widgets allow the +user to copy text from the output field but not change it. + +<p>The <a href="#Fl_Input.value"><tt>value()</tt></a> method is used to get or +set the string that is displayed: + +<ul><pre> +Fl_Input *input = new Fl_Input(x, y, width, height, "label"); +input->value("Now is the time for all good men..."); +</pre></ul> + +<H2>Valuators</H2> + +Unlike text widgets, valuators keep track of numbers instead of strings. +FLTK provides the following valuators: + +<ul> + <li><tt>Fl_Counter</tt> - A widget with arrow buttons that shows the + current value. + <li><tt>Fl_Dial</tt> - A round knob. + <li><tt>Fl_Roller</tt> - An SGI-like dolly widget. + <li><tt>Fl_Scrollbar</tt> - A standard scrollbar widget. + <li><tt>Fl_Slider</tt> - A scrollbar with a knob. + <li><tt>Fl_Value_Slider</tt> - A slider that shows the current value. +</ul> + +The <a href="#Fl_Valuator.value"><tt>value()</tt></a> method gets and sets the +current value of the widget. The <a href="#Fl_Valuator.minimum"> +<tt>minimum()</tt></a> and <a href="#Fl_Valuator.maximum"><tt>maximum</tt></a> +methods set the range of values that are reported by the widget. + +<H2>Groups</H2> + +The <tt>Fl_Group</tt> widget class is used as a general purpose "container" +widget. Besides grouping radio buttons, the groups are used to encapsulate +windows, tabs, and scrolled windows. The following group classes are available +with FLTK: + +<ul> + <li><tt>Fl_Double_Window</tt> - A double-buffered window on the screen. + <li><tt>Fl_Gl_Window</tt> - An OpenGL window on the screen. + <li><tt>Fl_Group</tt> - The base container class; can be used to group any widgets together. + <li><tt>Fl_Scroll</tt> - A scrolled window area. + <li><tt>Fl_Tabs</tt> - Displays child widgets as tabs. + <li><tt>Fl_Window</tt> - A window on the screen. +</ul> + +<H2>Setting the Size and Position of Widgets</H2> + +The size and position of widgets is usually set when you create them. You +can change this at any time using the <tt>position</tt>, <tt>resize()</tt>, +and <tt>size</tt> methods: + +<ul><pre> +button->position(x, y); +group->resize(x, y, width, height); +window->size(width, height); +</pre></ul> + +Changing the size or position of a widget will cause a redraw of that widget +and its children. + +<H2>Colors</H2> + +FLTK manages a virtual color palette of "standard" colors. The +standard colors are: + +<ul> + <li><tt>FL_BLACK</tt> + <li><tt>FL_RED</tt> + <li><tt>FL_GREEN</tt> + <li><tt>FL_YELLOW</tt> + <li><tt>FL_BLUE</tt> + <li><tt>FL_MAGENTA</tt> + <li><tt>FL_CYAN</tt> + <li><tt>FL_WHITE</tt> + <li><tt>FL_GRAY</tt> +</ul> + +The widget color can be set using the <tt>color()</tt> method: + +<ul><pre> +button->color(FL_RED); +</pre></ul> + +Similarly, the label color can be set using the <tt>labelcolor()</tt> method: + +<ul><pre> +button->labelcolor(FL_WHITE); +</pre></ul> + +<H2>Box Types</H2> + +<p>The type <tt>Fl_Boxtype</tt> stored and returned in <a href="#Fl_Widget.box"> +<tt>Fl_Widget::box()</tt></a> is an enumeration defined in +<a href="#enumerations"><tt><FL/Enumerations.H></tt></a>: + +<center><img src=boxtypes.gif width=80%></center> + +<tt>FL_NO_BOX</tt> means nothing is drawn at all, so whatever is +already on the screen remains. The <tt>FL_..._FRAME</tt> types only +draw their edges, leaving the center unchanged. In the above diagram +the blue color is the area that is not drawn by the box. + +<H3>Making your own Boxtypes</H3> + +You can define your own boxtypes by making a small function that +draws the box and adding a pointer to it to a table of boxtypes. + +<H4>The Drawing Function</H4> + +The drawing function is passed the bounding box and background +color for the widget: + +<ul><pre> +void xyz_draw(int x, int y, int w, int h, Fl_Color c) { +... +} +</pre></ul> + +A simple drawing function might fill a rectangle with the given +color and then draw a black outline: + +<ul><pre> +void xyz_draw(int x, int y, int w, int h, Fl_Color c) { + fl_color(c); + fl_rectf(x, y, w, h); + fl_color(FL_BLACK); + fl_rect(x, y, w, h); +} +</pre></ul> + +<H4>Adding Your Box Type</H4> + +The <tt>Fl::set_boxtype()</tt> method adds or replaces the +specified box type: + +<ul><pre> +#define XYZ_BOX FL_FREE_BOXTYPE + +Fl::set_boxtype(XYZ_BOX, xyz_draw, 1, 1, 2, 2); +</pre></ul> + +The last 4 arguments to <tt>Fl::set_boxtype()</tt> are the offsets +for the bounding box that should be subtracted when drawing the label +inside the box. + +<H2>Labels and Label Types</H2> + +The <tt>label()</tt>, <tt>align</tt>, <tt>labelfont()</tt>, <tt>labelsize()<tt>, +and <tt>labeltype()</tt> methods control the labeling of widgets. + +<H3>label()</H3> + +The <tt>label()</tt> method sets the string that is displayed for the label. +For the <tt>FL_SYMBOL_LABEL</tt> and image label types the string contains +the actual symbol or image data. + +<H3>align()</H3> + +The <tt>align()</tt> method positions the label. The following constants are +defined: + +<ul> + <li><tt>FL_ALIGN_CENTER</tt> - center the label in the widget. + <li><tt>FL_ALIGN_TOP</tt> - align the label at the top of the widget. + <li><tt>FL_ALIGN_BOTTOM</tt> - align the label at the bottom of the widget. + <li><tt>FL_ALIGN_LEFT</tt> - align the label to the left of the widget. + <li><tt>FL_ALIGN_RIGHT</tt> - align the label to the right of the widget. + <li><tt>FL_ALIGN_INSIDE</tt> - align the label inside the widget. + <li><tt>FL_ALIGN_CLIP</tt> - clip the label to the widget's bounding box. + <li><tt>FL_ALIGN_WRAP</tt> - wrap the label text as needed. +</ul> + +<H3>labeltype()</H3> + +The <tt>labeltype()</tt> method sets the type of the label. The following +standard label types are included: + +<ul> + <li><tt>FL_NORMAL_LABEL</tt> - draws the text. + <li><tt>FL_NO_LABEL</tt> - does nothing + <li><tt>FL_SYMBOL_LABEL</tt> - draws "@xyz" labels, see "<a href=#symbols>Symbol Labels</a>" + <li><tt>FL_SHADOW_LABEL</tt> - draws a drop shadow under the text + <li><tt>FL_ENGRAVED_LABEL</tt> - draws edges as though the text is engraved + <li><tt>FL_EMBOSSED_LABEL</tt> - draws edges as thought the text is raised +</ul> + +To make bitmaps or pixmaps you use a method on the +<a href="#Fl_Bitmap"><tt>Fl_Bitmap</tt></a> or +<a href="#Fl_Pixmap"><tt>Fl_Pixmap</tt></a> objects. + +<H4>Making Your Own Label Types</H4> + +Label types are actually indexes into a table of functions to draw +them. The primary purpose of this is to let you reuse the +<tt>label()</tt> pointer as a pointer to arbitrary data such as a +bitmap or pixmap. You can also use this to draw the labels in ways +inaccessible through the <tt>fl_font</tt> mechanisim (e.g. +<tt>FL_ENGRAVED_LABEL</tt>) or with program-generated letters or +symbology. + +<H5>Label Type Functions</H5> + +To setup your own label type you will need to write two functions +to draw and measure the label. The draw function is called with a +pointer to a <a href="#Fl_Label"><tt>Fl_Label</tt></a> structure +containing the label information, the bounding box for the label, +and the label alignment: + +<ul><pre> +void xyz_draw(Fl_Label *label, int x, int y, int w, int h, Fl_Align align) { +... +} +</pre></ul> + +The label should be drawn <i>inside</i> this bounding box, even if +<tt>FL_ALIGN_INSIDE</tt> is not enabled. The function is not called if +the label value is <tt>NULL</tt>. + +<p>The measure function is called with a pointer to a <a href="#Fl_Label"><tt>Fl_Label</tt></a> structure +and references to the width and height: + +<ul><pre> +void xyz_measure(Fl_Label *label, int &w, int &h) { +... +} +</pre></ul> + +It should measure the size of the label and set <tt>w</tt> and <tt>h</tt> to +the size it will occupy. + +<H5>Adding Your Label Type</H5> + +The <tt>Fl::set_labeltype</tt> method creates a label type using your +draw and measure functions: + +<ul><pre> +#define XYZ_LABEL FL_FREE_LABELTYPE + +Fl::set_labeltype(XYZ_LABEL, xyz_draw, xyz_measure); +</pre></ul> + +The label type number <tt>n</tt> can be any integer value starting at +the constant <tt>FL_FREE_LABELTYPE</tt>. Once you have added the label +type you can use the <tt>labeltype()</tt> method to select your label +type. + +<p>The <tt>Fl::set_labeltype</tt> method can also be used to overload an +existing label type such as <tt>FL_NORMAL_LABEL</tt>. + +<H4><a name="symbols">Symbol Labels</H4> + +<p>The <tt>FL_SYMBOL_LABEL</tt> label type uses the <tt>label()</tt> +string to look up a small drawing procedure in a hash table. For +historical reasons the string always starts with '@', if it starts with +something else (or the symbol is not found) the label is drawn +normally: + +<center><img src=symbols.gif></center> + +The @ sign may be followed by the following optional "formatting" +characters, in this order: + +<ul> + <li>'#' forces square scaling, rather than distortion to the + widget's shape. + + <li>+[1-9] or -[1-9] tweaks the scaling a little bigger or + smaller. + + <li>[1-9] - rotates by a multiple of 45 degrees. '6' does + nothing, the others point in the direction of that key on a + numeric keypad. +</ul> + +<H2>Callbacks</H2> + +Callbacks are functions that are called when the value of a widget changes. +A callback function is sent a <tt>Fl_Widget</tt> pointer of the widget that +changed and optionally a pointer to data of some sort: + +<ul><pre> +void xyz_callback(Fl_Widget *w, void *data) { +... +} +</pre></ul> + +The <tt>callback()</tt> method sets the callback function for a widget. You +can optionally pass a pointer to some data needed for the callback: + +<ul><pre> +int xyz_data; + +button->callback(xyz_callback, &xyz_data); +</pre></ul> + +Normally callbacks are performed only when the value of the widget +changes. You can change this using the +<a href="#Fl_Widget.when"><tt>when()</tt></a> method: + +<ul><pre> +button->when(FL_WHEN_NEVER); +button->when(FL_WHEN_CHANGED); +button->when(FL_WHEN_RELEASE); +button->when(FL_WHEN_RELEASE_ALWAYS); +button->when(FL_WHEN_ENTER_KEY); +button->when(FL_WHEN_ENTER_KEY_ALWAYS); +button->when(FL_WHEN_CHANGED | FL_WHEN_NOT_CHANGED); +</pre></ul> + +<H2>Shortcuts</H2> + +Shortcuts are key sequences that activate widgets (usually buttons or menu +items). The <tt>shortcut()</tt> method registers a shortcut for a widget: + +<ul><pre> +button->shortcut(FL_Enter); +button->shortcut(FL_SHIFT + 'b'); +button->shortcut(FL_CTRL + 'b'); +button->shortcut(FL_ALT + 'b'); +button->shortcut(FL_CTRL + FL_ALT + 'b'); +</pre></ul> + +The shortcut value is the key event value (the ASCII value or one of +the special keys like <tt>FL_Enter</tt>) combined with any modifiers +(like shift, alt, and control). + +</BODY> +</HTML> diff --git a/documentation/counter.gif b/documentation/counter.gif Binary files differnew file mode 100644 index 000000000..9784e467e --- /dev/null +++ b/documentation/counter.gif diff --git a/documentation/dial.gif b/documentation/dial.gif Binary files differnew file mode 100644 index 000000000..68b09c032 --- /dev/null +++ b/documentation/dial.gif diff --git a/documentation/drawing.html b/documentation/drawing.html new file mode 100644 index 000000000..2e78a7086 --- /dev/null +++ b/documentation/drawing.html @@ -0,0 +1,1295 @@ +<HTML> +<BODY> + +<H1>Chapter XXX - Drawing Things in FLTK</H1> + +<h2>When can you draw things in FLTK?</h2> + +There are only certain places you can execute drawing code in FLTK. +Calling these functions at other places will result in undefined +behavior! + +<ul> + +<li>The most common is inside the virtual method <a +href=subclass.html#draw>Fl_Widget::draw()</a>. To write code here, +you must subclass one of the existing Fl_Widget classes and implement +your own version of draw(). + +<p> + +<li>You can also write <a href=Boxtypes.html>boxtypes</a> and <a href += Labeltypes.html>labeltypes</a>. These are small procedures that can be +called by existing Fl_Widget draw() methods. These "types" are +identified by an 8-bit index that is stored in the widget's box(), +labeltype(), and possibly other properties. + +<p> + +<li>You can call <a +href=Fl_Window.html#make_current>Fl_Window::make_current()</a> to do +incremental update of a widget (use <a +href=Fl_Widget.html#window>Fl_Widget::window()</a> to find the +window). <i>Under X this only works for the base Fl_Window class, not +for double buffered, overlay, or OpenGL windows!</i> + +</ul> + +</ul><h2>FLTK Drawing functions<br>#include <FL/fl_draw.H></h2> + +<ul> +<li><a href=#clipping>Clipping</a> +<li><a href=#color>Colors</a> +<li><a href=#fast>Fast Shapes</a> +<li><a href=#vertex>Complex Shapes</a> +<li><a href=#text>Text</a> +<li><a href=images.html>Images</a> +<li><a href=#cursor>Cursor</a> +<li><a href=#overlay>Overlay</a> +<li><a href=Fl_Gl_Window.html#gl_start>Using OpenGL</a> +</ul> + +</ul><hr><h3>Clipping</h3> + +<p>You can limit all your drawing to a rectangular region by calling +fl_clip, and put the drawings back by using fl_pop_clip. This +rectangle is measured in pixels (it is unaffected by the current +transformation matrix). + +<p>In addition, the system may provide clipping when updating windows, +this clip region may be more complex than a simple rectangle. + +</ul><h4><code>void fl_clip(int x, int y, int w, int h);</code></h4><ul> + +Intesect the current clip region with a rectangle and push this new +region onto the stack. + +</ul><h4><code>void fl_pop_clip();</code></h4><ul> + +Restore the previous clip region. <i>You must call fl_pop_clip() once +for every time you call fl_clip(). If you return to FLTK with the +clip stack not empty unpredictable results occur.</i> + +</ul><h4><code>int fl_not_clipped(int x, int y, int w, int h);</code></h4><ul> + +Returns true if any of the rectangle intersects the current clip +region. If this returns false you don't have to draw the object. +<i>On X this returns 2 if the rectangle is partially clipped, and 1 if +it is entirely inside the clip region</i>. + +</ul><h4><code>int fl_clip_box(int x, int y, int w, int h,<br> +    int& X, int& Y, int& W, int& H);</code></h4><ul> + +Intersect the rectangle x,y,w,h with the current clip region and +returns the bounding box of the result in X,Y,W,H. Returns non-zero +if the resulting rectangle is different than the original. This can +be used to limit the necessary drawing to a rectangle. W and H are set to +zero if the rectangle is completely outside the region. + +</ul><hr><h3>Colors</h3> + +</ul><h4><code>void fl_color(Fl_Color);</code></h4><ul> + +<p>Set the color for all subsequent drawing operations. Fl_Color is +an enumeration type, all values are in the range 0-255. This is +<i>not</i> the X pixel, it is an internal table! The table provides +several general colors, a 24-entry gray ramp, and a 5x8x5 color cube. +All of these are named with poorly-documented symbols in <a +href=Enumerations.html><FL/Enumerations.H></a>. + +<p><i>Under X, a color cell will be allocated out of fl_colormap each +time you request an fl_color the first time. If the colormap fills up +then a least-squares algorithim is used to find the closest color.</i> + +</ul><h4><code>Fl_Color fl_color();</code></h4><ul> + +Returns the last fl_color() that was set. This can be used for state +save/restore. + +</ul><h4><code>void Fl::set_color(Fl_Color, uchar r, uchar g, uchar b); +<br>void Fl::get_color(Fl_Color, uchar &, uchar &, uchar &);</code></h4><ul> + +Set or get an entry in the fl_color index table. You can set it to +any 8-bit rgb color. <i>On X, if the index has been requested before, +the pixel is free'd. No pixel is allocated until fl_color(i) is used +again, and there is no guarantee that the same pixel will be used next +time.</i> + +</ul><h4><code>void fl_color(uchar r, uchar g, uchar +b);</code></h4><ul> + +<p>Set the color for all subsequent drawing operations. The closest +possible match to the rgb color is used. <i>Under X this works +perfectly for TrueColor visuals. For colormap visuals the nearest index +in the gray ramp or color cube is figured out, and fl_color(i) is done +with that, this can result in two approximations of the color and is +very inaccurate!</i> + +</ul><hr><h3>Fast Shapes</h3> + +These are used to draw almost all the FLTK widgets. They draw on +exact pixel boundaries and are as fast as possible, and their behavior +will be duplicated exactly on any platform FLTK is ported to. It is +undefined whether these are affected by the <a +href=#vertex>transformation matrix</a>, so you should only call these +while it is the identity. + +<p><i>All arguments are integers.</i> + +</ul><h4><code>void fl_rectf(x, y, w, h);</code></h4><ul> + +Color a rectangle that exactly fills the given bounding box. + +</ul><h4><code>void fl_rectf(x, y, w, h, uchar r, uchar g, uchar b);</code></h4><ul> + +Color a rectangle with "exactly" the passed r,g,b color. On screens +with less than 24 bits of color this is done by drawing a +solid-colored block using <a +href=images.html#fl_draw_image>fl_draw_image()</a> so that dithering +is produced. If you have 24 bit color, this fills the rectangle with a +single pixel value and is about 1 zillion times faster. + +</ul><h4><code>void fl_rect(x, y, w, h);</code></h4><ul> + +Draw a 1-pixel border <i>inside</i> this bounding box. + +</ul><h4><code>void fl_line(x, y, x1, y1); +<br>void fl_line(x, y, x1, y1, x2, y2);</code></h4><ul> + +Draw one or two 1-pixel thick lines between the given points. + +</ul><h4><code>void fl_loop(x, y, x1, y1, x2, y2); +<br>void fl_loop(x, y, x1, y1, x2, y2, x3, y3); +</code></h4><ul> + +Outline a 3 or 4-sided polygon with 1-pixel thick lines. + +</ul><h4><code>void fl_polygon(x, y, x1, y1, x2, y2); +<br>void fl_polygon(x, y, x1, y1, x2, y2, x3, y3); +</code></h4><ul> + +Fill a 3 or 4-sided polygon. The polygon must be convex. + +</ul><h4><code>void fl_xyline(x, y, x1, y1); +<br>void fl_xyline(x, y, x1, y1, x2); +<br>void fl_xyline(x, y, x1, y1, x2, y3); +</code></h4><ul> + +Draw 1-pixel wide horizontal and vertical lines. A horizontal line is +drawn first, then a vertical, then a horizontal. + +</ul><h4><code>void fl_yxline(x, y, y1); +<br>void fl_yxline(x, y, y1, x2); +<br>void fl_yxline(x, y, y1, x2, y3); +</code></h4><ul> + +Draw 1-pixel wide vertical and horizontal lines. A vertical line is +drawn first, then a horizontal, then a vertical. + +</ul><h4><code> +void fl_arc(x, y, w, h, double a1, double a2);<br> +void fl_pie(x, y, w, h, double a1, double a2);<br> +void fl_chord(x, y, w, h, double a1, double a2);</code></h4><ul> + +High-speed ellipse sections. These functions match the rather limited +circle drawing code provided by X and MSWindows. The advantage over using <a +href=#fl_arc>fl_arc</a> is that they are faster because they often use +the hardware, and they draw much nicer small circles, since the small +sizes are often hard-coded bitmaps. + +<p>If a complete circle is drawn it will fit inside the passed +bounding box. The two angles are measured in degrees counterclockwise +from 3'oclock and are the starting and ending angle of the arc, a2 +must be greater or equal to a1. + +<p>fl_arc draws a 1-pixel thick line (notice this has a different +number of arguments than the <a href=#fl_arc>fl_arc</a> described +below. + +<p>fl_pie draws a filled-in pie slice. This slice may extend outside +the line drawn by fl_arc, to avoid this use w-1 and h-1. + +<p>fl_chord is not yet implemented. + +</ul><hr><h3>Complex Shapes</h3> + +These functions let you draw arbitrary shapes with 2-D linear +transformations. The functionality matches PostScript. The exact +pixels filled in is less defined than for the above calls, so that FLTK +can take advantage of drawing hardware. (Both Xlib and MSWindows round +all the transformed verticies to integers before drawing the line +segments. This severely limits the accuracy of these functions for +complex graphics. Try using OpenGL instead) + +<p><i>All arguments are float.</i> + +</ul><h4><code>void fl_push_matrix(); +<br>void fl_pop_matrix();</code></h4><ul> + +Save and restore the current transformation. The maximum depth of the +stack is 4. + +</ul><h4><code>void fl_scale(x, y); +<br>void fl_scale(x); +<br>void fl_translate(x, y); +<br>void fl_rotate(d); +<br>void fl_mult_matrix(a, b, c, d, x, y);</code></h4><ul> + +Concat another transformation to the current one. The rotation angle +is in degrees (not radians) counter-clockwise. + +</ul><h4><code>void fl_begin_line(); +<br>void fl_end_line();</code></h4><ul> + +Start and end drawing 1-pixel thick lines. + +</ul><h4><code>void fl_begin_loop(); +<br>void fl_end_loop();</code></h4><ul> + +Start and end drawing a closed sequence of 1-pixel thick lines. + +</ul><h4><code>void fl_begin_polygon(); +<br>void fl_end_polygon();</code></h4><ul> + +Start and end drawing a convex filled polygon. + +</ul><h4><code>void fl_begin_complex_polygon(); +<br>void fl_gap(); +<br>void fl_end_complex_polygon();</code></h4><ul> + +Start and end drawing a complex filled polygon. This polygon may be +concave, may have holes in it, or may be several disconnected pieces. +Call fl_gap() to seperate loops of the path (it is unnecessary but +harmless to call fl_gap() before the first vertex, after the last one, +or several times in a row). For portability, you should only draw +polygons that appear the same whether "even/odd" or "non-zero" +"winding rules" are used to fill them. This mostly means that holes +should be drawn in the opposite direction of the outside. + +<p><i>fl_gap() should only be called between +fl_begin/end_complex_polygon(). To outline the polygon, use +fl_begin_loop() and replace each fl_gap() with +fl_end_loop();fl_begin_loop().</i> + +</ul><h4><code>void fl_vertex(x, y);</code></h4><ul> + +Add a single vertex to the current path. + +</ul><h4><code>void fl_curve(int x,int y,int x1,int y1,int x2,int +y2,int x3,int y3);</code></h4><ul> + +Add a series of points on a Bezier curve to the path. The curve ends +(and two of the points) are at x,y and x3,y3. + +</ul><h4><code>void fl_arc(x, y, r, start, end);</code></h4><ul> + +Add a series of points to the current path on the arc of a circle (you +can get elliptical paths by using scale and rotate before calling +this). <i>x,y</i> are the center of the circle, and <i>r</i> is it's +radius. fl_arc() takes <i>start</i> and <i>end</i> angles that are +measured in degrees counter-clockwise from 3 o'clock. If <i>end</i> +is less than <i>start</i> then it draws clockwise. + +</ul><h4><code>void fl_circle(x, y, r);</code></h4><ul> + +fl_circle() is equivalent to fl_arc(...,0,360) but may be faster. It +must be the <i>only</i> thing in the path: if you want a circle as +part of a complex polygon you must use fl_arc(). <i>Under Xlib and +MSWindows this draws incorrectly if the transformation is both rotated +and non-square scaled.</i> + +</ul><hr><h3>Text</h3> + +All text is drawn in the <a href=#fl_font>current font</a>. It is +undefined whether this location or the characters are modified by the +current transformation. + +</ul><h4><code>void fl_draw(const char*, float x, float y); +<br>void fl_draw(const char*, int n, float x, float y);</code></h4><ul> + +Draw a null terminated string or an array of <i>n</i> characters +starting at the given location. + +</ul><h4><code>void fl_draw(const char*, int x,int y,int w,int h, Fl_Align);</code></h4><ul> + +Fancy string drawing function which is used to draw all the labels. +The string is formatted and aligned inside the passed box. Handles +'\t' and '\n', expands all other control characters to ^X, and aligns +inside or against the edges of the box. See <a +href=Fl_Widget.html#align>Fl_Widget::align()</a> for values for +<i>align</i>. The value FL_ALIGN_INSIDE is ignored, this always +prints inside the box. + +</ul><h4><code>void fl_measure(const char*, int& w, int& h);</code></h4><ul> + +Measure how wide and tall the string will be when printed by the +fl_draw(...align) function. If the incoming w is non-zero it will +wrap to that width. + +</ul><h4><code>int fl_height();</code></h4><ul> + +Recommended minimum line spacing for the current font. You can also +just use the value of <i>size</i> passed to <a +href=#fl_font>fl_font()</a>. + +</ul><h4><code>int fl_descent();</code></h4><ul> + +Recommended distance above the bottom of a fl_height() tall box to +draw the text at so it looks centered vertically in that box. + +</ul><h4><code>float fl_width(const char*); +<br>float fl_width(const char*, int n); +<br>float fl_width(uchar);</code></h4><ul> + +Return the width of a null-terminated string, a sequence of n +characters, and a single character. + +</ul><h4><code>const char* fl_shortcut_label(ulong);</code></h4><ul> + +Unparse a shortcut value as used by <a +href=Fl_Button.html#shortcut>Fl_Button</a> or <a +href=Fl_Menu.html>Fl_Menu_Item</a> into a human-readable string like +"Alt+N". This only works if the shortcut is a character key or a +numbered Function key. If the shortcut is zero an empty string is +returned. The return value points at a static buffer that is +overwritten with each call. + +</ul><hr><h3>Fonts</h3> + +</ul><h4><code>void fl_font(int face, int size);</code></h4><ul> + +Set the current font, which is then used by the routines described +above. You may call this outside a draw context if necessary to call +fl_width(), but on X this will open the display. + +<p>The font is identified by a <i>face</i> and a <i>size</i>. The +size of the font is measured in <i>pixels</i> (ie. it is not +"resolution [in]dependent"). Lines should be spaced <i>size</i> +pixels apart (or more). + +<p>The <i>face</i> is an index into an internal table. Initially only +the first 16 faces are filled in. There are symbolic names for them: +FL_HELVETICA, FL_TIMES, FL_COURIER, and modifier values FL_BOLD and +FL_ITALIC which can be added to these, and FL_SYMBOL and +FL_ZAPF_DINGBATS. Faces greater than 255 cannot be used in Fl_Widget +labels, since it stores the index as a byte. + +</ul><h4><code>int fl_font();<br> +int fl_size();</code></h4><ul> + +Returns the face and size set by the most recent fl_font(a,b). This +can be used to save/restore the font. + +</ul><h4><code>const char* Fl::get_font(int face);</code></h4><ul> + +Get the string for this face. This string is different for each face. +Under X this value is passed to XListFonts to get all the sizes of +this face. + +</ul><h4><code>const char* Fl::get_font_name(int face, int* attributes=0);</code></h4><ul> + +Get a human-readable string describing the family of this face. This +is useful if you are presenting a choice to the user. There is no +guarantee that each face has a different name. The return value +points to a static buffer that is overwritten each call. + +<p>The integer pointed to by <i>attributes</i> (if the pointer is not +zero) is set to zero, <code>FL_BOLD</code>(1) or +<code>FL_ITALIC</code>(2) or <code>FL_BOLD|FL_ITALIC</code> (maybe +more attributes will be defined in the future). To locate a "family" +of fonts, search forward and back for a set with non-zero attributes, +these faces along with the face with a zero attribute before them +constitute a family. + +</ul><h4><code>int get_font_sizes(int face, int*& sizep);</code></h4><ul> + +Return an array of sizes in <i>sizep</i>. The return value is the +length of this array. The sizes are sorted from smallest to largest +and indicate what sizes can be given to fl_font() that will be matched +exactly (fl_font() will pick the closest size for other sizes). A +zero in the first location of the array indicates a scalable font, +where any size works, although the array may list sizes that work +"better" than others. Warning: the returned array points at a static +buffer that is overwritten each call. Under X this will open the +display. + +</ul><h4><code>int Fl::set_font(int face, const char*);</code></h4><ul> + +Change a face. The string pointer is simply stored, the string is not +copied, so the string must be in static memory. + +</ul><h4><code>int Fl::set_font(int face, int from);</code></h4><ul> + +Copy one face to another. + +</ul><h4><code>int Fl::set_fonts(const char* = 0);</code></h4><ul> + +FLTK will open the display, and add every font on the server to the +face table. It will attempt to put "families" of faces together, so +that the normal one is first, followed by bold, italic, and bold +italic. + +<p>The optional argument is a string to describe the set of fonts to +add. Passing NULL will select only fonts that have the ISO8859-1 +character set (and are thus usable by normal text). Passing "-*" will +select all fonts with any encoding as long as they have normal X font +names with dashes in them. Passing "*" will list every font that +exists (on X this may produce some strange output). Other values may +be useful but are system dependent. On MSWindows NULL selects fonts +with ISO8859-1 encoding and non-NULL selects all fonts. + +<p>Return value is how many faces are in the table after this is done. + +</ul><hr><h2>Bitmaps, Pixmaps and Images</h2> + +<a href=images.html#direct>Click here for information on drawing images</a> + +</ul><hr><h3>Cursor</h3> + +</ul><h4><code>void fl_cursor(Fl_Cursor, Fl_Color=FL_WHITE, Fl_Color=FL_BLACK);</code></h4><ul> + +Change the cursor. Depending on the system this may affect the cursor +everywhere, or only when it is pointing at the window that is current +when you call this. For portability you should change the cursor back +to the default in response to FL_LEAVE events. + +<p>The type Fl_Cursor is an enumeration defined in <a +href=Enumerations.html><Enumerations.H></a>. The +double-headed arrows are bitmaps provided by FLTK on X, the others are +provided by system-defined cursors. Under X you can get any XC_cursor +value by passing <code>Fl_Cursor((XC_foo/2)+1)</code>. + +<p><ul> +<li><code>FL_CURSOR_DEFAULT</code> (0) usually an arrow +<li><code>FL_CURSOR_ARROW</code> +<li><code>FL_CURSOR_CROSS</code> - crosshair +<li><code>FL_CURSOR_WAIT</code> - watch or hourglass +<li><code>FL_CURSOR_INSERT</code> - I-beam +<li><code>FL_CURSOR_HAND</code> - hand (uparrow on MSWindows) +<li><code>FL_CURSOR_HELP</code> - question mark +<li><code>FL_CURSOR_MOVE</code> - 4-pointed arrow +<li><code>FL_CURSOR_NS</code> - up/down arrow +<li><code>FL_CURSOR_WE</code> - left/right arrow +<li><code>FL_CURSOR_NWSE</code> - diagonal arrow +<li><code>FL_CURSOR_NESW</code> - diagonal arrow +<li><code>FL_CURSOR_NONE</code> - invisible +</ul> + +</ul><hr><h3>Overlay rectangle</h3> + +</ul><h4><code>void fl_overlay_rect(int x, int y, int w, int h);<br> +void fl_overlay_clear();</code></h4><ul> + +<p>Big kludge to draw interactive selection rectangles without using +the overlay. FLTK will xor a single rectangle outline over a window. +Calling this will erase any previous rectangle (by xor'ing it), and +then draw the new one. Calling fl_overlay_clear() will erase the +rectangle without drawing a new one. Using this is tricky. You +should make a widget with both a handle() and draw() method. draw() +should call fl_overlay_clear() before doing anything else. Your +handle() method should call window()->make_current() and then +fl_overlay_rect() after FL_DRAG events, and should call +fl_overlay_clear() after a FL_RELEASE event. + +</ul><p><a href = index.html>(back to contents)</a> +</BODY> +</HTML> +<title>Drawing Images in FLTK</title> +<h2>Drawing Images in FLTK</h2> + +To draw images, you can either do it directly from data in your +memory, or you can create <a href=#Fl_Bitmap>Fl_Bitmap</a> or <a +href=#Fl_Image>Fl_Image</a> or <a href=#Fl_Pixmap>Fl_Pixmap</a> +objects. The advantage of drawing directly is that it is more +intuitive, and it is faster if the image data changes more often than +it is redrawn. The advantage of using the object is that FLTK will +cache translated forms of the image (on X it uses a server pixmap) and +thus redrawing it is <i>much</i> faster. + +<a name=direct> +<h2><hr>Direct Image Drawing<br> +#include <FL/fl_draw.H></h2> + +<p>It is undefined whether the location or drawing of the image is +affected by the current transformation, so you should only call these +when it is the identity. + +<p><i>All untyped arguments are integers.</i> + +</ul><h4><code> +void fl_draw_bitmap(const uchar*, X, Y, W, H, LD = 0);</code></h4><ul> + +This function is planned but not yet implemented (it may be impossible +under X without allocating a pixmap). + +<a name=fl_draw_image> +</ul><h4><code> +void fl_draw_image(const uchar*, X, Y, W, H, D = 3, LD = 0);<br> +void fl_draw_image_mono(const uchar*, X, Y, W, H, D = 1, LD = 0); +</code></h4><ul> + +Draw an 8-bit per color rgb image. The pointer points at the "r" data +of the top-left pixel. Data must be in r,g,b order. X, Y are where +to put the top-left corner. W and H define the size of the image. D +is the delta to add to the pointer between pixels, it may be any value +greater or equal to 3, or it can be negative to flip the image +horizontally. LD is the delta to add to the pointer between lines (if +0 is passed it uses W*D), and may be larger than W*D to crop data, or +negative to flip the image vertically. + +<p>It is highly recommended that you put the following code before the +first show() of <i>any</i> window in your program to get rid of the +dithering if possible: + +<ul><p><code>Fl::visual(FL_RGB)</code></ul> + +<p>Gray scale (1-channel) images may be drawn. This is done if abs(D) +is less than 3, or by calling <code>fl_draw_image_mono</code>. Only +one 8-bit sample is used for each pixel, and (on screens with +different numbers of bits for red, green, and blue) only gray colors +are used. Setting D greater than 1 will let you display one channel +of a color image. + +<p><i>The X version does not support all possible visuals.</i> If FLTK +cannot draw the image in the current visual it will abort. FLTK +supports any visual of 8 bits or less, and all common TrueColor +visuals up to 32 bits. + +</ul><h4><code> +typedef void (*fl_draw_image_cb)(void*, x, y, w, uchar*);<br> +void fl_draw_image(fl_draw_image_cb, void*, X, Y, W, H, D = 3);<br> +void fl_draw_image_mono(fl_draw_image_cb, void*, X, Y, W, H, D = 1); +</code></h4><ul> + +Call the passed function to provide each scan line of the image. This +lets you generate the image as it is being drawn, or do arbitrary +decompression of stored data (provided it can be decompressed to +individual scan lines easily). + +<p>The callback is called with the void* user data pointer (this can +be used to point at a structure of information about the image), and +the x, y, and w of the scan line desired from the image. 0,0 is the +upper-left corner (<i>not X,Y</i>). A pointer to a buffer to put the +data into is passed. You must copy w pixels from scanline y, starting +at pixel x, to this buffer. + +<p>Due to cropping, less than the whole image may be requested. So x +may be greater than zero, the first y may be greater than zero, and w +may be less than W. The buffer is long enough to store the entire W*D +pixels, this is for convienence with some decompression schemes where +you must decompress the entire line at once: decompress it into the +buffer, and then if x is not zero, memcpy the data over so the x'th +pixel is at the start of the buffer. + +<p>You can assumme the y's will be consecutive, except the first one +may be greater than zero. + +<p>If D is 4 or more, you must fill in the unused bytes with zero. + +</ul><h4><code> +int fl_draw_pixmap(char** data, X, Y, Fl_Color=FL_GRAY);</code></h4><ul> + +Draw XPM image data, with the top-left corner at the given position. +The images is dithered on 8-bit displays so you won't lose color space +for programs displaying both images and pixmaps. This function +returns zero if there was any error decoding the xpm data. + +<p>To use an XPM, do "<code>#include "foo.xpm"</code>" and then +"<code>fl_draw_pixmap(foo, X, Y)</code>". + +<p>In the current version the XPM data is converted to 8-bit full +color and passed through fl_draw_image(). This is obviously not the +most efficient way to do it, and has the same visual limitations as +listed above for fl_draw_image(). Transparent colors are replaced by +the optional Fl_Color argument (this may change in the future). + +<p><a href=xpm.html>FLTK supports some (questionable) enhancements to +the XPM format.</a> + +</ul><h4><code> +int fl_measure_pixmap(char** data, int &w, int +&h);</code></h4><ul> + +An XPM image contains the dimensions in it's data. This function +finds and returns the width and height. The return value is non-zero +if it parsed the dimensions ok, and zero if there is any problem. + +</ul> + +<a name=Fl_Bitmap> +<h2><hr>class Fl_Bitmap +<br>#include <FL/Fl_Bitmap.H></h2> + +This object encapsulates the width, height, and bits of an Xbitmap +(XBM), and allows you to make an Fl_Widget use a bitmap as a label, or +to just draw the bitmap directly. <i>Under X it will create an +offscreen pixmap the first time it is drawn, and copy this each +subsequent time it is drawn</i>. + +<h4><code>Fl_Bitmap(const char *bits, int W, int H); +<br>Fl_Bitmap(const uchar *bits, int W, int H);</code></h4> + +Construct from an Xbitmap. The bits pointer is simply copied to the +object, so it must point at persistent storage. I provide two +constructors because various X implementations disagree about the type +of bitmap data. To use an XBM file, +<code>#include "foo.xbm"</code>, and then do "<code>new +Fl_Bitmap(foo_bits,foo_width,foo_height)</code>" + +<h4><code>~Fl_Bitmap()</code></h4> + +The destructor will destroy any X pixmap created. It does not do +anything to the bits data. + +<h4><code>void draw(int x, int y, int w, int h, int ox=0, int oy=0);</code></h4> + +<i>x,y,w,h</i> indicates a destination rectangle. <i>ox,oy,w,h</i> is +a source rectangle. This source rectangle from the bitmap is drawn in +the destination. 1 bits are drawn with the current color, 0 bits are +unchanged. The source rectangle may extend outside the bitmap (i.e. ox +and oy may be negative and w and h may be bigger than the bitmap) and +this area is left unchanged. + +<h4><code>void draw(int x, int y);</code></h4> + +Draws the bitmap with the upper-left corner at <i>x,y</i>. This is +the same as doing <code>draw(x,y,this->w,this->h,0,0)</code>. + +<h4><code>void label(Fl_Widget *);</code></h4> + +Change the label() and the labeltype() of the widget to draw the +bitmap. 1 bits will be drawn with the labelcolor(), zero bits will be +unchanged. You can use the same bitmap for many widgets. + +<a name=Fl_Pixmap> +<h2><hr>class Fl_Pixmap +<br>#include <FL/Fl_Pixmap.H></h2> + +This object encapsulates the data from an XPM image, and allows you to +make an Fl_Widget use a pixmap as a label, or to just draw the pixmap +directly. <i>Under X it will create an offscreen pixmap the first +time it is drawn, and copy this each subsequent time it is drawn</i>. + +<p>The current implementation converts the pixmap to 8 bit color data +and uses <a href=#fl_draw_image>fl_draw_image()</a> to draw +it. Thus you will get dithered colors on an 8 bit screen. + +<h4><code>Fl_Pixmap(char * const * data);</code></h4> + +Construct from XPM data. The data pointer is simply copied to the +object, so it must point at persistent storage. To use an XPM file, +<code>#include "foo.xpm"</code>, and then do "<code>new +Fl_Pixmap(foo)</code>" + +<h4><code>~Fl_Pixmap()</code></h4> + +The destructor will destroy any X pixmap created. It does not do +anything to the data. + +<h4><code>void draw(int x, int y, int w, int h, int ox=0, int oy=0);</code></h4> + +<i>x,y,w,h</i> indicates a destination rectangle. <i>ox,oy,w,h</i> is +a source rectangle. This source rectangle is copied to the +destination. The source rectangle may extend outside the pixmap +(i.e. ox and oy may be negative and w and h may be bigger than the +pixmap) and this area is left unchanged. + +<h4><code>void draw(int x, int y);</code></h4> + +Draws the image with the upper-left corner at <i>x,y</i>. This is +the same as doing <code>draw(x,y,this->w,this->h,0,0)</code>. + +<h4><code>void label(Fl_Widget *);</code></h4> + +Change the label() and the labeltype() of the widget to draw the +pixmap. You can use the same pixmap for many widgets. + +<a name=Fl_Image> +<h2><hr>class Fl_Image +<br>#include <FL/Fl_Image.H></h2> + +This object encapsulates a full-color RGB image, and allows you to +make an Fl_Widget use a Image as a label, or to just draw the Image +directly. <i>Under X it will create an offscreen pixmap the first +time it is drawn, and copy this each subsequent time it is drawn</i>. + +<p>See <a href=#fl_draw_image>fl_draw_image()</a> for what +happens. On 8 bit screens dithering is used. + +<h4><code>Fl_Image(char uchar *data, int W, int H, int D=3, int LD=0);</code></h4> + +Construct from a pointer to RGB data. W and H are the size of the +image in pixels. D is the delta between pixels (it may be more than 3 +to skip alpha or other data, or negative to flip the image +left/right). LD is the delta between lines (it may be more than D*W +to crop images, or negative to flip the image vertically). The data +pointer is simply copied to the object, so it must point at persistent +storage. + +<h4><code>~Fl_Image()</code></h4> + +The destructor will destroy any X pixmap created. It does not do +anything to the data. + +<h4><code>void draw(int x, int y, int w, int h, int ox=0, int oy=0);</code></h4> + +<i>x,y,w,h</i> indicates a destination rectangle. <i>ox,oy,w,h</i> is +a source rectangle. This source rectangle is copied to the +destination. The source rectangle may extend outside the image +(i.e. ox and oy may be negative and w and h may be bigger than the +image) and this area is left unchanged. + +<h4><code>void draw(int x, int y);</code></h4> + +Draws the image with the upper-left corner at <i>x,y</i>. This is +the same as doing <code>draw(x,y,this->w,this->h,0,0)</code>. + +<h4><code>void label(Fl_Widget *);</code></h4> + +Change the label() and the labeltype() of the widget to draw the +Image. You can use the same Image for many widgets. + +<p><a href = index.html>(back to contents)</a> +<title>FLTK enhancements to the XPM format</title> +<h2>FLTK enhancements to the XPM format</h2> + +<p>I made some additions to XPM that may be good, or intensely +disliked by X purists. I do not know if the changes are compatable +with current XPM. + +<p>The change was to make a "compressed colormap" that avoids +XParseColor(), and gives the actual color values (which is really what +everybody wants!). Only colormaps of this form, and ones where the +colors are named as "#rrggbb", will be portable to non-X platforms. + +<p>A compressed colormap is indicated by the number of colors being +negative. The colormap is then given as an array of 4*numcolors +characters. Each color is described by 4 characters: the index +character, and the red, green, and blue value (for 2-character indexes +each color needs 5 characters). + +<p>XPM files support a single transparent index. I require this index +to be ' ' (space). To indicate that ' ' is transparent, it should be +first in the color table. To make ' ' not be transparent, put it +somewhere other than first in the table. + +<p>To make the XPM files easily parseable, but still portable to most +C compilers, I suggest the following format: + +<pre> +/* XPM */ +static char * name[] = { +/* width height ncolors chars_per_pixel */ +"64 64 -4 1 ", +/* colormap */ +"\ + \x50\x50\x80\ +.\xff\xff\x00\ +r\xff\x00\x00\ +b\x00\x00\x00", +/* pixels */ +" bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb ", +" bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb ", +" bb............................................bb ", +... +</pre> + +<p>All lines starting with "/*" are optional. Parsers should handle +'\' at the end of the line and \xNN and \NNN characters. This +requires the C compiler to parse \xNN characters. +<HTML> +<BODY> + +<H1>Chapter XXX - Drawing Things in FLTK</H1> + +<h2>When can you draw things in FLTK?</h2> + +There are only certain places you can execute drawing code in FLTK. +Calling these functions at other places will result in undefined +behavior! + +<ul> + +<li>The most common is inside the virtual method <a +href=subclass.html#draw>Fl_Widget::draw()</a>. To write code here, +you must subclass one of the existing Fl_Widget classes and implement +your own version of draw(). + +<p> + +<li>You can also write <a href=Boxtypes.html>boxtypes</a> and <a href += Labeltypes.html>labeltypes</a>. These are small procedures that can be +called by existing Fl_Widget draw() methods. These "types" are +identified by an 8-bit index that is stored in the widget's box(), +labeltype(), and possibly other properties. + +<p> + +<li>You can call <a +href=Fl_Window.html#make_current>Fl_Window::make_current()</a> to do +incremental update of a widget (use <a +href=Fl_Widget.html#window>Fl_Widget::window()</a> to find the +window). <i>Under X this only works for the base Fl_Window class, not +for double buffered, overlay, or OpenGL windows!</i> + +</ul> + +</ul><h2>FLTK Drawing functions<br>#include <FL/fl_draw.H></h2> + +<ul> +<li><a href=#clipping>Clipping</a> +<li><a href=#color>Colors</a> +<li><a href=#fast>Fast Shapes</a> +<li><a href=#vertex>Complex Shapes</a> +<li><a href=#text>Text</a> +<li><a href=images.html>Images</a> +<li><a href=#cursor>Cursor</a> +<li><a href=#overlay>Overlay</a> +<li><a href=Fl_Gl_Window.html#gl_start>Using OpenGL</a> +</ul> + +</ul><hr><h3>Clipping</h3> + +<p>You can limit all your drawing to a rectangular region by calling +fl_clip, and put the drawings back by using fl_pop_clip. This +rectangle is measured in pixels (it is unaffected by the current +transformation matrix). + +<p>In addition, the system may provide clipping when updating windows, +this clip region may be more complex than a simple rectangle. + +</ul><h4><code>void fl_clip(int x, int y, int w, int h);</code></h4><ul> + +Intesect the current clip region with a rectangle and push this new +region onto the stack. + +</ul><h4><code>void fl_pop_clip();</code></h4><ul> + +Restore the previous clip region. <i>You must call fl_pop_clip() once +for every time you call fl_clip(). If you return to FLTK with the +clip stack not empty unpredictable results occur.</i> + +</ul><h4><code>int fl_not_clipped(int x, int y, int w, int h);</code></h4><ul> + +Returns true if any of the rectangle intersects the current clip +region. If this returns false you don't have to draw the object. +<i>On X this returns 2 if the rectangle is partially clipped, and 1 if +it is entirely inside the clip region</i>. + +</ul><h4><code>int fl_clip_box(int x, int y, int w, int h,<br> +    int& X, int& Y, int& W, int& H);</code></h4><ul> + +Intersect the rectangle x,y,w,h with the current clip region and +returns the bounding box of the result in X,Y,W,H. Returns non-zero +if the resulting rectangle is different than the original. This can +be used to limit the necessary drawing to a rectangle. W and H are set to +zero if the rectangle is completely outside the region. + +</ul><hr><h3>Colors</h3> + +</ul><h4><code>void fl_color(Fl_Color);</code></h4><ul> + +<p>Set the color for all subsequent drawing operations. Fl_Color is +an enumeration type, all values are in the range 0-255. This is +<i>not</i> the X pixel, it is an internal table! The table provides +several general colors, a 24-entry gray ramp, and a 5x8x5 color cube. +All of these are named with poorly-documented symbols in <a +href=Enumerations.html><FL/Enumerations.H></a>. + +<p><i>Under X, a color cell will be allocated out of fl_colormap each +time you request an fl_color the first time. If the colormap fills up +then a least-squares algorithim is used to find the closest color.</i> + +</ul><h4><code>Fl_Color fl_color();</code></h4><ul> + +Returns the last fl_color() that was set. This can be used for state +save/restore. + +</ul><h4><code>void Fl::set_color(Fl_Color, uchar r, uchar g, uchar b); +<br>void Fl::get_color(Fl_Color, uchar &, uchar &, uchar &);</code></h4><ul> + +Set or get an entry in the fl_color index table. You can set it to +any 8-bit rgb color. <i>On X, if the index has been requested before, +the pixel is free'd. No pixel is allocated until fl_color(i) is used +again, and there is no guarantee that the same pixel will be used next +time.</i> + +</ul><h4><code>void fl_color(uchar r, uchar g, uchar +b);</code></h4><ul> + +<p>Set the color for all subsequent drawing operations. The closest +possible match to the rgb color is used. <i>Under X this works +perfectly for TrueColor visuals. For colormap visuals the nearest index +in the gray ramp or color cube is figured out, and fl_color(i) is done +with that, this can result in two approximations of the color and is +very inaccurate!</i> + +</ul><hr><h3>Fast Shapes</h3> + +These are used to draw almost all the FLTK widgets. They draw on +exact pixel boundaries and are as fast as possible, and their behavior +will be duplicated exactly on any platform FLTK is ported to. It is +undefined whether these are affected by the <a +href=#vertex>transformation matrix</a>, so you should only call these +while it is the identity. + +<p><i>All arguments are integers.</i> + +</ul><h4><code>void fl_rectf(x, y, w, h);</code></h4><ul> + +Color a rectangle that exactly fills the given bounding box. + +</ul><h4><code>void fl_rectf(x, y, w, h, uchar r, uchar g, uchar b);</code></h4><ul> + +Color a rectangle with "exactly" the passed r,g,b color. On screens +with less than 24 bits of color this is done by drawing a +solid-colored block using <a +href=images.html#fl_draw_image>fl_draw_image()</a> so that dithering +is produced. If you have 24 bit color, this fills the rectangle with a +single pixel value and is about 1 zillion times faster. + +</ul><h4><code>void fl_rect(x, y, w, h);</code></h4><ul> + +Draw a 1-pixel border <i>inside</i> this bounding box. + +</ul><h4><code>void fl_line(x, y, x1, y1); +<br>void fl_line(x, y, x1, y1, x2, y2);</code></h4><ul> + +Draw one or two 1-pixel thick lines between the given points. + +</ul><h4><code>void fl_loop(x, y, x1, y1, x2, y2); +<br>void fl_loop(x, y, x1, y1, x2, y2, x3, y3); +</code></h4><ul> + +Outline a 3 or 4-sided polygon with 1-pixel thick lines. + +</ul><h4><code>void fl_polygon(x, y, x1, y1, x2, y2); +<br>void fl_polygon(x, y, x1, y1, x2, y2, x3, y3); +</code></h4><ul> + +Fill a 3 or 4-sided polygon. The polygon must be convex. + +</ul><h4><code>void fl_xyline(x, y, x1, y1); +<br>void fl_xyline(x, y, x1, y1, x2); +<br>void fl_xyline(x, y, x1, y1, x2, y3); +</code></h4><ul> + +Draw 1-pixel wide horizontal and vertical lines. A horizontal line is +drawn first, then a vertical, then a horizontal. + +</ul><h4><code>void fl_yxline(x, y, y1); +<br>void fl_yxline(x, y, y1, x2); +<br>void fl_yxline(x, y, y1, x2, y3); +</code></h4><ul> + +Draw 1-pixel wide vertical and horizontal lines. A vertical line is +drawn first, then a horizontal, then a vertical. + +</ul><h4><code> +void fl_arc(x, y, w, h, double a1, double a2);<br> +void fl_pie(x, y, w, h, double a1, double a2);<br> +void fl_chord(x, y, w, h, double a1, double a2);</code></h4><ul> + +High-speed ellipse sections. These functions match the rather limited +circle drawing code provided by X and MSWindows. The advantage over using <a +href=#fl_arc>fl_arc</a> is that they are faster because they often use +the hardware, and they draw much nicer small circles, since the small +sizes are often hard-coded bitmaps. + +<p>If a complete circle is drawn it will fit inside the passed +bounding box. The two angles are measured in degrees counterclockwise +from 3'oclock and are the starting and ending angle of the arc, a2 +must be greater or equal to a1. + +<p>fl_arc draws a 1-pixel thick line (notice this has a different +number of arguments than the <a href=#fl_arc>fl_arc</a> described +below. + +<p>fl_pie draws a filled-in pie slice. This slice may extend outside +the line drawn by fl_arc, to avoid this use w-1 and h-1. + +<p>fl_chord is not yet implemented. + +</ul><hr><h3>Complex Shapes</h3> + +These functions let you draw arbitrary shapes with 2-D linear +transformations. The functionality matches PostScript. The exact +pixels filled in is less defined than for the above calls, so that FLTK +can take advantage of drawing hardware. (Both Xlib and MSWindows round +all the transformed verticies to integers before drawing the line +segments. This severely limits the accuracy of these functions for +complex graphics. Try using OpenGL instead) + +<p><i>All arguments are float.</i> + +</ul><h4><code>void fl_push_matrix(); +<br>void fl_pop_matrix();</code></h4><ul> + +Save and restore the current transformation. The maximum depth of the +stack is 4. + +</ul><h4><code>void fl_scale(x, y); +<br>void fl_scale(x); +<br>void fl_translate(x, y); +<br>void fl_rotate(d); +<br>void fl_mult_matrix(a, b, c, d, x, y);</code></h4><ul> + +Concat another transformation to the current one. The rotation angle +is in degrees (not radians) counter-clockwise. + +</ul><h4><code>void fl_begin_line(); +<br>void fl_end_line();</code></h4><ul> + +Start and end drawing 1-pixel thick lines. + +</ul><h4><code>void fl_begin_loop(); +<br>void fl_end_loop();</code></h4><ul> + +Start and end drawing a closed sequence of 1-pixel thick lines. + +</ul><h4><code>void fl_begin_polygon(); +<br>void fl_end_polygon();</code></h4><ul> + +Start and end drawing a convex filled polygon. + +</ul><h4><code>void fl_begin_complex_polygon(); +<br>void fl_gap(); +<br>void fl_end_complex_polygon();</code></h4><ul> + +Start and end drawing a complex filled polygon. This polygon may be +concave, may have holes in it, or may be several disconnected pieces. +Call fl_gap() to seperate loops of the path (it is unnecessary but +harmless to call fl_gap() before the first vertex, after the last one, +or several times in a row). For portability, you should only draw +polygons that appear the same whether "even/odd" or "non-zero" +"winding rules" are used to fill them. This mostly means that holes +should be drawn in the opposite direction of the outside. + +<p><i>fl_gap() should only be called between +fl_begin/end_complex_polygon(). To outline the polygon, use +fl_begin_loop() and replace each fl_gap() with +fl_end_loop();fl_begin_loop().</i> + +</ul><h4><code>void fl_vertex(x, y);</code></h4><ul> + +Add a single vertex to the current path. + +</ul><h4><code>void fl_curve(int x,int y,int x1,int y1,int x2,int +y2,int x3,int y3);</code></h4><ul> + +Add a series of points on a Bezier curve to the path. The curve ends +(and two of the points) are at x,y and x3,y3. + +</ul><h4><code>void fl_arc(x, y, r, start, end);</code></h4><ul> + +Add a series of points to the current path on the arc of a circle (you +can get elliptical paths by using scale and rotate before calling +this). <i>x,y</i> are the center of the circle, and <i>r</i> is it's +radius. fl_arc() takes <i>start</i> and <i>end</i> angles that are +measured in degrees counter-clockwise from 3 o'clock. If <i>end</i> +is less than <i>start</i> then it draws clockwise. + +</ul><h4><code>void fl_circle(x, y, r);</code></h4><ul> + +fl_circle() is equivalent to fl_arc(...,0,360) but may be faster. It +must be the <i>only</i> thing in the path: if you want a circle as +part of a complex polygon you must use fl_arc(). <i>Under Xlib and +MSWindows this draws incorrectly if the transformation is both rotated +and non-square scaled.</i> + +</ul><hr><h3>Text</h3> + +All text is drawn in the <a href=#fl_font>current font</a>. It is +undefined whether this location or the characters are modified by the +current transformation. + +</ul><h4><code>void fl_draw(const char*, float x, float y); +<br>void fl_draw(const char*, int n, float x, float y);</code></h4><ul> + +Draw a null terminated string or an array of n characters in the +current font, starting at the given location. + +</ul><h4><code>void fl_draw(const char*, int x,int y,int w,int h, Fl_Align);</code></h4><ul> + +Fancy string drawing function which is used to draw all the labels. +The string is formatted and aligned inside the passed box. Handles +'\t' and '\n', expands all other control characters to ^X, and aligns +inside or against the edges of the box. See <a +href=Fl_Widget.html#align>Fl_Widget::align()</a> for values for +<i>align</i>. The value FL_ALIGN_INSIDE is ignored, this always +prints inside the box. + +</ul><h4><code>void fl_measure(const char*, int& w, int& h);</code></h4><ul> + +Measure how wide and tall the string will be when printed by the +fl_draw(...align) function. If the incoming w is non-zero it will +wrap to that width. + +</ul><h4><code>int fl_height();</code></h4><ul> + +Recommended minimum line spacing for the current font. You can also +just use the value of <i>size</i> passed to <a +href=#fl_font>fl_font()</a>. + +</ul><h4><code>int fl_descent();</code></h4><ul> + +Recommended distance above the bottom of a fl_height() tall box to +draw the text at so it looks centered vertically in that box. + +</ul><h4><code>float fl_width(const char*); +<br>float fl_width(const char*, int n); +<br>float fl_width(uchar);</code></h4><ul> + +Return the width of a null-terminated string, a sequence of n +characters, and a single character. + +</ul><h4><code>const char* fl_shortcut_label(ulong);</code></h4><ul> + +Unparse a shortcut value as used by <a +href=Fl_Button.html#shortcut>Fl_Button</a> or <a +href=Fl_Menu.html>Fl_Menu_Item</a> into a human-readable string like +"Alt+N". This only works if the shortcut is a character key or a +numbered Function key. If the shortcut is zero an empty string is +returned. The return value points at a static buffer that is +overwritten with each call. + +</ul><hr><h3>Fonts</h3> + +</ul><h4><code>void fl_font(int face, int size);</code></h4><ul> + +Set the current font, which is then used by the routines described +above. You may call this outside a draw context if necessary to call +fl_width(), but on X this will open the display. + +<p>The font is identified by a <i>face</i> and a <i>size</i>. The +size of the font is measured in <i>pixels</i> (ie. it is not +"resolution [in]dependent"). Lines should be spaced <i>size</i> +pixels apart (or more). + +<p>The <i>face</i> is an index into an internal table. Initially only +the first 16 faces are filled in. There are symbolic names for them: +FL_HELVETICA, FL_TIMES, FL_COURIER, and modifier values FL_BOLD and +FL_ITALIC which can be added to these, and FL_SYMBOL and +FL_ZAPF_DINGBATS. Faces greater than 255 cannot be used in Fl_Widget +labels, since it stores the index as a byte. + +</ul><h4><code>int fl_font();<br> +int fl_size();</code></h4><ul> + +Returns the face and size set by the most recent fl_font(a,b). This +can be used to save/restore the font. + +</ul><h4><code>const char* Fl::get_font(int face);</code></h4><ul> + +Get the string for this face. This string is different for each face. +Under X this value is passed to XListFonts to get all the sizes of +this face. + +</ul><h4><code>const char* Fl::get_font_name(int face, int* attributes=0);</code></h4><ul> + +Get a human-readable string describing the family of this face. This +is useful if you are presenting a choice to the user. There is no +guarantee that each face has a different name. The return value +points to a static buffer that is overwritten each call. + +<p>The integer pointed to by <i>attributes</i> (if the pointer is not +zero) is set to zero, <code>FL_BOLD</code>(1) or +<code>FL_ITALIC</code>(2) or <code>FL_BOLD|FL_ITALIC</code> (maybe +more attributes will be defined in the future). To locate a "family" +of fonts, search forward and back for a set with non-zero attributes, +these faces along with the face with a zero attribute before them +constitute a family. + +</ul><h4><code>int get_font_sizes(int face, int*& sizep);</code></h4><ul> + +Return an array of sizes in <i>sizep</i>. The return value is the +length of this array. The sizes are sorted from smallest to largest +and indicate what sizes can be given to fl_font() that will be matched +exactly (fl_font() will pick the closest size for other sizes). A +zero in the first location of the array indicates a scalable font, +where any size works, although the array may list sizes that work +"better" than others. Warning: the returned array points at a static +buffer that is overwritten each call. Under X this will open the +display. + +</ul><h4><code>int Fl::set_font(int face, const char*);</code></h4><ul> + +Change a face. The string pointer is simply stored, the string is not +copied, so the string must be in static memory. + +</ul><h4><code>int Fl::set_font(int face, int from);</code></h4><ul> + +Copy one face to another. + +</ul><h4><code>int Fl::set_fonts(const char* = 0);</code></h4><ul> + +FLTK will open the display, and add every font on the server to the +face table. It will attempt to put "families" of faces together, so +that the normal one is first, followed by bold, italic, and bold +italic. + +<p>The optional argument is a string to describe the set of fonts to +add. Passing NULL will select only fonts that have the ISO8859-1 +character set (and are thus usable by normal text). Passing "-*" will +select all fonts with any encoding as long as they have normal X font +names with dashes in them. Passing "*" will list every font that +exists (on X this may produce some strange output). Other values may +be useful but are system dependent. On MSWindows NULL selects fonts +with ISO8859-1 encoding and non-NULL selects all fonts. + +<p>Return value is how many faces are in the table after this is done. + +</ul><hr><h2>Bitmaps, Pixmaps and Images</h2> + +<a href=images.html#direct>Click here for information on drawing images</a> + +</ul><hr><h3>Cursor</h3> + +</ul><h4><code>void fl_cursor(Fl_Cursor, Fl_Color=FL_WHITE, Fl_Color=FL_BLACK);</code></h4><ul> + +Change the cursor. Depending on the system this may affect the cursor +everywhere, or only when it is pointing at the window that is current +when you call this. For portability you should change the cursor back +to the default in response to FL_LEAVE events. + +<p>The type Fl_Cursor is an enumeration defined in <a +href=Enumerations.html><Enumerations.H></a>. The +double-headed arrows are bitmaps provided by FLTK on X, the others are +provided by system-defined cursors. Under X you can get any XC_cursor +value by passing <code>Fl_Cursor((XC_foo/2)+1)</code>. + +<p><ul> +<li><code>FL_CURSOR_DEFAULT</code> (0) usually an arrow +<li><code>FL_CURSOR_ARROW</code> +<li><code>FL_CURSOR_CROSS</code> - crosshair +<li><code>FL_CURSOR_WAIT</code> - watch or hourglass +<li><code>FL_CURSOR_INSERT</code> - I-beam +<li><code>FL_CURSOR_HAND</code> - hand (uparrow on MSWindows) +<li><code>FL_CURSOR_HELP</code> - question mark +<li><code>FL_CURSOR_MOVE</code> - 4-pointed arrow +<li><code>FL_CURSOR_NS</code> - up/down arrow +<li><code>FL_CURSOR_WE</code> - left/right arrow +<li><code>FL_CURSOR_NWSE</code> - diagonal arrow +<li><code>FL_CURSOR_NESW</code> - diagonal arrow +<li><code>FL_CURSOR_NONE</code> - invisible +</ul> + +</ul><hr><h3>Overlay rectangle</h3> + +</ul><h4><code>void fl_overlay_rect(int x, int y, int w, int h);<br> +void fl_overlay_clear();</code></h4><ul> + +<p>Big kludge to draw interactive selection rectangles without using +the overlay. FLTK will xor a single rectangle outline over a window. +Calling this will erase any previous rectangle (by xor'ing it), and +then draw the new one. Calling fl_overlay_clear() will erase the +rectangle without drawing a new one. Using this is tricky. You +should make a widget with both a handle() and draw() method. draw() +should call fl_overlay_clear() before doing anything else. Your +handle() method should call window()->make_current() and then +fl_overlay_rect() after FL_DRAG events, and should call +fl_overlay_clear() after a FL_RELEASE event. + +</ul><p><a href = index.html>(back to contents)</a> +</BODY> +</HTML> diff --git a/documentation/editor-replace.gif b/documentation/editor-replace.gif Binary files differnew file mode 100644 index 000000000..6098ead60 --- /dev/null +++ b/documentation/editor-replace.gif diff --git a/documentation/editor.gif b/documentation/editor.gif Binary files differnew file mode 100644 index 000000000..3f3301e47 --- /dev/null +++ b/documentation/editor.gif diff --git a/documentation/editor.html b/documentation/editor.html new file mode 100644 index 000000000..60dca040c --- /dev/null +++ b/documentation/editor.html @@ -0,0 +1,603 @@ +<HTML> +<BODY> + +<H1 ALIGN=RIGHT>4 - Designing a Simple Text Editor</H1> + +This chapter takes you through the design of a simple FLTK-based text editor. + +<H2>Determining the Goals of the Text Editor</H2> + +Since this will be the first big project you'll be doing with FLTK, lets define +what we want our text editor to do: + +<ol> + <li>Menu_Bar/menus for all functions. + <li>Edit a single text file. + <li>Load from a file. + <li>Save to a file. + <li>Cut/copy/delete/paste functions. + <li>Search and replace functions. + <li>Keep track of when the file has been changed. +</ol> + +<H2>Designing the Main Window</H2> + +Now that we've outlined the goals for our editor, we can begin with the design +of our GUI. Obviously the first thing that we need is a window: + +<ul><pre> +Fl_Window *window; + +window = new Fl_Window(640, 480, "Text Editor"); +</pre></ul> + +<H2>Variables</H2> + +Our text editor will need some global variables to keep track of things: + +<ul><pre> +Fl_Window *window; +Fl_Menu_Bar *menubar; +Fl_Multiline_Input *input; +Fl_Window *replace_dlg; +Fl_Input *replace_find; +Fl_Input *replace_with; +Fl_Button *replace_all; +Fl_Return_Button *replace_next; +Fl_Button *replace_cancel; + +int changed = 0; +char filename[1024] = ""; +char search[256] = ""; +</pre></ul> + +The <tt>window</tt> variable is our top-level window described previously. +We'll cover the other variables as we build the application. + +<H2>Menu_Bars and Menus</H2> + +The first goal requires us to use a menubar and menus that define +each function the editor needs to perform. The +<a href="#Fl_Menu_Item"><tt>Fl_Menu_Item</tt></a> structure is used to +define the menus and items in a menubar: + +<ul><pre> +Fl_Menu_Item menuitems[] = { + { "&File", 0, 0, 0, FL_SUBMENU }, + { "&New", FL_ALT + 'n', new_cb }, + { "&Open...", FL_ALT + 'o', open_cb, 0, FL_MENU_DIVIDER }, + { "&Save", FL_ALT + 's', save_cb }, + { "Save &As...", FL_ALT + FL_SHIFT + 's', saveas_cb, 0, FL_MENU_DIVIDER }, + { "&Quit", FL_ALT + 'q', quit_cb }, + { 0 }, + + { "&Edit", 0, 0, 0, FL_SUBMENU }, + { "&Undo", FL_ALT + 'z', undo_cb, 0, FL_MENU_DIVIDER }, + { "Cu&t", FL_ALT + 'x', cut_cb }, + { "&Copy", FL_ALT + 'c', copy_cb }, + { "&Paste", FL_ALT + 'v', paste_cb }, + { "&Delete", 0, delete_cb }, + { 0 }, + + { "&Search", 0, 0, 0, FL_SUBMENU }, + { "&Find...", FL_ALT + 'f', find_cb }, + { "F&ind Again", FL_ALT + 'g', find2_cb }, + { "&Replace...", FL_ALT + 'r', replace_cb }, + { "Re&place Again", FL_ALT + 't', replace2_cb }, + { 0 }, + + { 0 } +}; +</pre></ul> + +Once we have the menus defined we can create the <tt>Fl_Menu_Bar</tt> widget +and assign the menus to it with: + +<ul><pre> +Fl_Menu_Bar *menubar = new Fl_Menu_Bar(0, 0, 640, 30); +menubar->menu(menuitems); +</pre></ul> + +We'll define the callback functions later. + +<H2>Editing the Text</H2> + +To keep things simple our text editor will use the +<a href="#Fl_Multiline_Input"><tt>Fl_Multiline_Input</tt></a> widget to +edit the text: + +<ul><pre> +Fl_Multiline_Input *input = new Fl_Multiline_Input(0, 30, 640, 450); +</pre></ul> + +So that we can keep track of changes to the file, we also want to add a +"changed" callback: + +<ul><pre> +input->callback(changed_cb); +input->when(FL_WHEN_CHANGED); +</pre></ul> + +Finally, we want to use a mono-spaced font like <tt>FL_COURIER</tt>: + +<ul><pre> +input->textfont(FL_COURIER); +</pre></ul> + +<H2>The Replace Dialog</H2> + +We can use the FLTK convenience functions for many of the editor's +dialogs, however the replace dialog needs its own custom window. To +keep things simple we will have a "find" string, a "replace" string, +and "replace all", "replace next", and "cancel" buttons. The strings +are just <tt>Fl_Input</tt> widgets, the "replace all" and "cancel" +buttons are <tt>Fl_Button</tt> widgets, and the "replace next " button +is a <tt>Fl_Return_Button</tt> widget: + +<center><img src=editor-replace.gif></center> + +<ul><pre> +Fl_Window *replace_dlg = new Fl_Window(300, 105, "Replace"); +Fl_Input *replace_find = new Fl_Input(70, 10, 200, 25, "Find:"); +Fl_Input *replace_with = new Fl_Input(70, 40, 200, 25, "Replace:"); +Fl_Button *replace_all = new Fl_Button(10, 70, 90, 25, "Replace All"); +Fl_Button *replace_next = new Fl_Button(105, 70, 120, 25, "Replace Next"); +Fl_Button *replace_cancel = new Fl_Button(230, 70, 60, 25, "Cancel"); +</pre></ul> + +<H2>Callbacks</H2> + +Now that we've defined the GUI components of our editor, we need to define +our callback functions. + +<H3>changed_cb()</H3> + +This function will be called whenever the user changes any text in the +<tt>input</tt> widget: + +<ul><pre> +void changed_cb(void) { + set_changed(1); +} +</pre></ul> + +The <tt>set_changed()</tt> function is one that we will write to set the +changed status on the current file. We're doing it this way because some +of the other callbacks will set the changed status to 0, and also because +we want to show the changed status in the window's title bar. + +<H3>copy_cb()</H3> + +This callback function will call <a href="#Fl_Input.copy"> +<tt>input->copy()</tt></a> to copy the currently selected text to the +clipboard: + +<ul><pre> +void copy_cb(void) { + input->copy(); +} +</pre></ul> + +<H3>cut_cb()</H3> + +This callback function will call <a href="#Fl_Input_.copy"> +<tt>input->copy()</tt></a> to copy the currently selected text to the +clipboard and then <a href="#Fl_Input_.cut"><tt>input->cut()</tt></a> +to delete it: + +<ul><pre> +void cut_cb(void) { + input->copy(); + input->cut(); +} +</pre></ul> + +<H3>delete_cb()</H3> + +This callback function will call <a href="#Fl_Input_.cut"> +<tt>input->cut()</tt></a> to delete the selected text: + +<ul><pre> +void delete_cb(void) { + input->cut(); +} +</pre></ul> + +<H3>find_cb()</H3> + +This callback function asks for a search string using the +<a href="#fl_input"><tt>fl_input()</tt></a> convenience function and +then calls the <tt>find2_cb()</tt> function to find the string: + +<ul><pre> +void find_cb(void) { + const char *val; + + val = fl_input("Search String:", search); + if (val != NULL) { + // User entered a string - go find it! + strcpy(search, val); + find2_cb(); + } +} +</pre></ul> + +<H3>find2_cb()</H3> + +This function will find the next occurrence of the search string. If the +search string is blank then we want to pop up the search dialog: + +<ul><pre> +void find2_cb(void) { + const char *val, *found; + int pos; + + if (search[0] == '\0') { + // Search string is blank; get a new one... + find_cb(); + return; + } + + val = input->value() + input->mark(); + found = strstr(val, search); + + if (found != NULL) { + // Found a match; update the position and mark... + pos = input->mark() + found - val; + input->position(pos, pos + strlen(search)); + } + else fl_alert("No occurrences of \'%s\' found!", search); +} +</pre></ul> + +If the search string cannot be found we use the <a href="#fl_alert"> +<tt>fl_alert()</tt></a> convenience function to display a message to +that effect. + +<H3>new_cb()</H3> + +This callback function will clear the input widget and current filename. +It also calls the <tt>check_save()</tt> function to give the user the +opportunity to save the current file first as needed: + +<ul><pre> +void new_cb(void) { + if (changed) + if (!check_save()) return; + + filename[0] = '\0'; + input->value(""); + set_changed(0); +} +</pre></ul> + +<H3>open_cb()</H3> + +This callback function will ask the user for a filename and then load +the specified file into the input widget and current filename. It also +calls the <tt>check_save()</tt> function to give the user the +opportunity to save the current file first as needed: + +<ul><pre> +void open_cb(void) { + char *newfile; + + if (changed) + if (!check_save()) return; + + newfile = fl_file_chooser("Open File?", "*", filename); + if (newfile != NULL) load_file(newfile); +} +</pre></ul> + +We call the <tt>load_file()</tt> function to actually load the file. + +<H3>paste_cb()</H3> + +This callback function will send a FL_PASTE message to the <tt>input</tt> +widget using the <a href="#paste"><tt>Fl::paste()</tt> method: + +<ul><pre> +void paste_cb(void) { + Fl::paste(*input); +} +</pre></ul> + +<H3>quit_cb()</H3> + +The quit callback will first see if the current file has been modified, +and if so give the user a chance to save it. It then hides the main window: + +<ul><pre> +void quit_cb(void) { + if (changed) + if (!check_save()) + return; + + window->hide(); +} +</pre></ul> + +<H3>replace_cb()</H3> + +The replace callback just shows the replace dialog: + +<ul><pre> +void replace_cb(void) { + replace_dlg->show(); +} +</pre></ul> + +<H3>replace2_cb()</H3> + +This callback will replace the next occurence of the replacement string. If +nothing has been entered for the replacement string, then the replace dialog +is displayed instead: + +<ul><pre> +void replace2_cb() { + const char *find, *val, *found; + int pos; + + find = replace_find->value(); + if (find[0] == '\0') { + // Search string is blank; get a new one... + replace_dlg->show(); + return; + } + + val = input->value() + input->position(); + found = strstr(val, find); + + if (found != NULL) { + // Found a match; update the position and replace text... + pos = input->position() + found - val; + input->replace(pos, pos + strlen(find), replace_with->value()); + input->position(pos + strlen(replace_with->value())); + } + else fl_alert("No occurrences of \'%s\' found!", find); +} +</pre></ul> + +<H3>replall_cb()</H3> + +This callback will replace all occurences of the search string in the file: + +<ul><pre> +void replall_cb() { + const char *find, *val, *found; + int pos; + int times; + + find = replace_find->value(); + if (find[0] == '\0') { + // Search string is blank; get a new one... + replace_dlg->show(); + return; + } + + input->position(0); + times = 0; + + // Loop through the whole string + do { + val = input->value() + input->position(); + found = strstr(val, find); + + if (found != NULL) { + // Found a match; update the position and replace text... + times ++ + pos = input->position() + found - val; + input->replace(pos, pos + strlen(find), replace_with->value()); + input->position(pos + strlen(replace_with->value())); + } + } while (found != NULL); + + if (times > 0) fl_message("Replaced %d occurrences.", times); + else fl_alert("No occurrences of \'%s\' found!", find); +} +</pre></ul> + +<H3>replcan_cb()</H3> + +This callback just hides the replace dialog: + +<ul><pre> +void replcan_cb() { + replace_dlg->hide(); +} +</pre></ul> + +<H3>save_cb()</H3> + +This callback saves the current file. If the current filename is blank it +calls the "save as" callback: + +<ul><pre> +void save_cb(void) { + if (filename[0] == '\0') { + // No filename - get one! + saveas_cb(); + return; + } + else save_file(filename); +} +</pre></ul> + +The <tt>save_file()</tt> function saves the current file to the specified +filename. + +<H3>saveas_cb()</H3> + +This callback asks the user for a filename and saves the current file: + +<ul><pre> +void saveas_cb(void) { + char *newfile; + + newfile = fl_file_chooser("Save File As?", "*", filename); + if (newfile != NULL) save_file(newfile); +} +</pre></ul> + +The <tt>save_file()</tt> function saves the current file to the specified +filename. + +<H3>undo_cb()</H3> + +The undo callback just calls the <a href="#Fl_Input_.undo"> +<tt>undo()</tt></a> method: + +<ul><pre> +void undo_cb(void) { + input->undo(); +} +</pre></ul> + +<H2>Other Functions</H2> + +Now that we've defined the callback functions, we need our support functions +to make it all work: + +<H3>check_save()</H3> + +This function checks to see if the current file needs to be saved. If +so, it asks the user if they want to save it: + +<ul><pre> +int check_save(void) { + if (!changed) return 1; + + if (fl_ask("The current file has not been saved.\n" + "Would you like to save it now?")) { + // Save the file... + save_cb(); + + return !changed; + } + else return (1); +} +</pre></ul> + +<H3>load_file()</H3> + +This function loads the specified file into the <tt>input</tt> widget: + +<ul><pre> +void load_file(char *newfile) { + FILE *fp; + char buffer[8192]; + int nbytes; + int pos; + + input->value(""); + + fp = fopen(newfile, "r"); + if (fp != NULL) { + // Was able to open file; let's read from it... + strcpy(filename, newfile); + pos = 0; + + while ((nbytes = fread(buffer, 1, sizeof(buffer), fp)) > 0) { + input->replace(pos, pos, buffer, nbytes); + pos += nbytes; + } + + fclose(fp); + input->position(0); + set_changed(0); + } else { + // Couldn't open file - say so... + fl_alert("Unable to open \'%s\' for reading!"); + } +} +</pre></ul> + +When loading the file we use the <a href="#Fl_Input_.replace"> +<tt>input->replace()</tt> method to "replace" the text at the end of +the buffer. The <tt>pos</tt> variable keeps track of the end of the +buffer. + +<H3>save_file()</H3> + +This function saves the current buffer to the specified file: + +<ul><pre> +void save_file(char *newfile) { + FILE *fp; + + fp = fopen(newfile, "w"); + if (fp != NULL) { + // Was able to create file; let's write to it... + strcpy(filename, newfile); + + if (fwrite(input->value(), 1, input->size(), fp) < 1) { + fl_alert("Unable to write file!"); + fclose(fp); + return; + } + + fclose(fp); + set_changed(0); + } else { + // Couldn't open file - say so... + fl_alert("Unable to create \'%s\' for writing!"); + } +} +</pre></ul> + +<H3>set_changed()</H3> + +This function sets the <tt>changed</tt> variable and updates the window label +accordingly: + +<ul><pre> +void set_changed(int c) { + if (c != changed) { + char title[1024]; + char *slash; + + changed = c; + + if (filename[0] == '\0') strcpy(title, "Untitled"); + else { + slash = strrchr(filename, '/'); + if (slash == NULL) slash = strrchr(filename, '\\'); + + if (slash != NULL) strcpy(title, slash + 1); + else strcpy(title, filename); + } + + if (changed) strcat(title, " (modified)"); + + window->label(title); + } +} +</pre></ul> + +<H2>Compiling the Editor</H2> + +The complete source for our text editor can be found in the +<tt>test/editor.cxx</tt> source file. Both the Makefile and Visual C++ +workspace include the necessary rules to build the editor. You can +also compile it using a standard compiler with: + +<ul><pre> +CC -o editor editor.cxx -lfltk -lXext -lX11 -lm +</pre></ul> + +As noted in <a href="#basics">Chapter 1</a>, you may need to include +compiler and linker options to tell them where to find the FLTK library. +Also, the <tt>CC</tt> command may also be called <tt>gcc</tt> or +<tt>c++</tt> on your system. + +<p>Congratulations, you've just built your own text editor! + +<H2>The Final Product</H2> + +The final editor window should look like the image below: + +<center><img src=editor.gif></center> + +</BODY> +</HTML> diff --git a/documentation/enumerations.html b/documentation/enumerations.html new file mode 100644 index 000000000..355437a73 --- /dev/null +++ b/documentation/enumerations.html @@ -0,0 +1,328 @@ +<HTML> +<BODY> +<H1><A NAME="enumerations">C - FLTK Enumerations.H</A></H1> + +Here are the values of all the public-visible enumerations used by fltk: + +<pre> +#include <FL/Enumerations.H> + +// +// The FLTK version number; this is changed slightly from the beta versions +// because the old "const double" definition would not allow for conditional +// compilation... +// +// FL_VERSION is a double that describes the major and minor version numbers. +// Version 1.1 is actually stored as 1.01 to allow for more than 9 minor +// releases. +// +// The FL_MAJOR_VERSION, FL_MINOR_VERSION, and FL_PATCH_VERSION constants +// give the integral values for the major, minor, and patch releases +// respectively. +// + +#define FL_MAJOR_VERSION 1 +#define FL_MINOR_VERSION 0 +#define FL_PATCH_VERSION 0 +#define FL_VERSION ((double)FL_MAJOR_VERSION + \ + (double)FL_MINOR_VERSION * 0.01) + +typedef unsigned char uchar; +typedef unsigned long ulong; +typedef unsigned int u32; // you must fix if not 32 bits on your machine! + +enum Fl_Event { // events + FL_NO_EVENT = 0, + FL_PUSH = 1, + FL_RELEASE = 2, + FL_ENTER = 3, + FL_LEAVE = 4, + FL_DRAG = 5, + FL_FOCUS = 6, + FL_UNFOCUS = 7, + FL_KEYBOARD = 8, + FL_CLOSE = 9, + FL_MOVE = 10, + FL_SHORTCUT = 11, + FL_DEACTIVATE = 13, + FL_ACTIVATE = 14, + FL_HIDE = 15, + FL_SHOW = 16, + FL_PASTE = 17, + FL_SELECTIONCLEAR = 18 +}; + +enum Fl_When { // Fl_Widget::when(): + FL_WHEN_NEVER = 0, + FL_WHEN_CHANGED = 1, + FL_WHEN_RELEASE = 4, + FL_WHEN_RELEASE_ALWAYS= 6, + FL_WHEN_ENTER_KEY = 8, + FL_WHEN_ENTER_KEY_ALWAYS=10, + FL_WHEN_NOT_CHANGED = 2 // modifier bit to disable changed() test +}; + +// Fl::event_key() and Fl::get_key(n) (use ascii letters for all other keys): +#define FL_Button 0xfee8 // use Fl_Button+n for mouse button n +#define FL_BackSpace 0xff08 +#define FL_Tab 0xff09 +#define FL_Enter 0xff0d +#define FL_Pause 0xff13 +#define FL_Scroll_Lock 0xff14 +#define FL_Escape 0xff1b +#define FL_Home 0xff50 +#define FL_Left 0xff51 +#define FL_Up 0xff52 +#define FL_Right 0xff53 +#define FL_Down 0xff54 +#define FL_Page_Up 0xff55 +#define FL_Page_Down 0xff56 +#define FL_End 0xff57 +#define FL_Print 0xff61 +#define FL_Insert 0xff63 +#define FL_Menu 0xff67 // the "menu/apps" key on XFree86 +#define FL_Num_Lock 0xff7f +#define FL_KP 0xff80 // use FL_KP+'x' for 'x' on numeric keypad +#define FL_KP_Enter 0xff8d // same as Fl_KP+'\r' +#define FL_KP_Last 0xffbd // use to range-check keypad +#define FL_F 0xffbd // use FL_F+n for function key n +#define FL_F_Last 0xffe0 // use to range-check function keys +#define FL_Shift_L 0xffe1 +#define FL_Shift_R 0xffe2 +#define FL_Control_L 0xffe3 +#define FL_Control_R 0xffe4 +#define FL_Caps_Lock 0xffe5 +#define FL_Meta_L 0xffe7 // the left MSWindows key on XFree86 +#define FL_Meta_R 0xffe8 // the right MSWindows key on XFree86 +#define FL_Alt_L 0xffe9 +#define FL_Alt_R 0xffea +#define FL_Delete 0xffff + +// Fl::event_state(): +#define FL_SHIFT 0x00010000 +#define FL_CAPS_LOCK 0x00020000 +#define FL_CTRL 0x00040000 +#define FL_ALT 0x00080000 +#define FL_NUM_LOCK 0x00100000 // most X servers do this? +#define FL_META 0x00400000 // correct for XFree86 +#define FL_SCROLL_LOCK 0x00800000 // correct for XFree86 +#define FL_BUTTON1 0x01000000 +#define FL_BUTTON2 0x02000000 +#define FL_BUTTON3 0x04000000 + +enum Fl_Boxtype { // boxtypes (if you change these you must fix fl_boxtype.C): + FL_NO_BOX = 0, FL_FLAT_BOX, + + FL_UP_BOX, FL_DOWN_BOX, + FL_UP_FRAME, FL_DOWN_FRAME, + FL_THIN_UP_BOX, FL_THIN_DOWN_BOX, + FL_THIN_UP_FRAME, FL_THIN_DOWN_FRAME, + FL_ENGRAVED_BOX, FL_EMBOSSED_BOX, + FL_ENGRAVED_FRAME, FL_EMBOSSED_FRAME, + FL_BORDER_BOX, _FL_SHADOW_BOX, + FL_BORDER_FRAME, _FL_SHADOW_FRAME, + _FL_ROUNDED_BOX, _FL_RSHADOW_BOX, + _FL_ROUNDED_FRAME, _FL_RFLAT_BOX, + _FL_ROUND_UP_BOX, _FL_ROUND_DOWN_BOX, + _FL_DIAMOND_UP_BOX, _FL_DIAMOND_DOWN_BOX, + _FL_OVAL_BOX, _FL_OSHADOW_BOX, + _FL_OVAL_FRAME, _FL_OFLAT_BOX +}; +extern Fl_Boxtype define_FL_ROUND_UP_BOX(); +#define FL_ROUND_UP_BOX define_FL_ROUND_UP_BOX() +#define FL_ROUND_DOWN_BOX (Fl_Boxtype)(define_FL_ROUND_UP_BOX()+1) +extern Fl_Boxtype define_FL_SHADOW_BOX(); +#define FL_SHADOW_BOX define_FL_SHADOW_BOX() +#define FL_SHADOW_FRAME (Fl_Boxtype)(define_FL_SHADOW_BOX()+2) +extern Fl_Boxtype define_FL_ROUNDED_BOX(); +#define FL_ROUNDED_BOX define_FL_ROUNDED_BOX() +#define FL_ROUNDED_FRAME (Fl_Boxtype)(define_FL_ROUNDED_BOX()+2) +extern Fl_Boxtype define_FL_RFLAT_BOX(); +#define FL_RFLAT_BOX define_FL_RFLAT_BOX() +extern Fl_Boxtype define_FL_RSHADOW_BOX(); +#define FL_RSHADOW_BOX define_FL_RSHADOW_BOX() +extern Fl_Boxtype define_FL_DIAMOND_BOX(); +#define FL_DIAMOND_UP_BOX define_FL_DIAMOND_BOX() +#define FL_DIAMOND_DOWN_BOX (Fl_Boxtype)(define_FL_DIAMOND_BOX()+1) +extern Fl_Boxtype define_FL_OVAL_BOX(); +#define FL_OVAL_BOX define_FL_OVAL_BOX() +#define FL_OSHADOW_BOX (Fl_Boxtype)(define_FL_OVAL_BOX()+1) +#define FL_OVAL_FRAME (Fl_Boxtype)(define_FL_OVAL_BOX()+2) +#define FL_OFLAT_BOX (Fl_Boxtype)(define_FL_OVAL_BOX()+3) + +// conversions of box types to other boxtypes: +inline Fl_Boxtype down(Fl_Boxtype b) {return (Fl_Boxtype)(b|1);} +inline Fl_Boxtype frame(Fl_Boxtype b) {return (Fl_Boxtype)(b|2);} + +// back-compatability box types: +#define FL_FRAME FL_ENGRAVED_FRAME +#define FL_FRAME_BOX FL_ENGRAVED_BOX +#define FL_CIRCLE_BOX FL_ROUND_DOWN_BOX +#define FL_DIAMOND_BOX FL_DIAMOND_DOWN_BOX + +enum Fl_Labeltype { // labeltypes: + FL_NORMAL_LABEL = 0, + FL_NO_LABEL, + _FL_SYMBOL_LABEL, + _FL_SHADOW_LABEL, + _FL_ENGRAVED_LABEL, + _FL_EMBOSSED_LABEL, + _FL_BITMAP_LABEL, + _FL_PIXMAP_LABEL, + _FL_IMAGE_LABEL, + _FL_MULTI_LABEL, + FL_FREE_LABELTYPE +}; +extern Fl_Labeltype define_FL_SYMBOL_LABEL(); +#define FL_SYMBOL_LABEL define_FL_SYMBOL_LABEL() +extern Fl_Labeltype define_FL_SHADOW_LABEL(); +#define FL_SHADOW_LABEL define_FL_SHADOW_LABEL() +extern Fl_Labeltype define_FL_ENGRAVED_LABEL(); +#define FL_ENGRAVED_LABEL define_FL_ENGRAVED_LABEL() +extern Fl_Labeltype define_FL_EMBOSSED_LABEL(); +#define FL_EMBOSSED_LABEL define_FL_EMBOSSED_LABEL() + +enum Fl_Align { // align() values + FL_ALIGN_CENTER = 0, + FL_ALIGN_TOP = 1, + FL_ALIGN_BOTTOM = 2, + FL_ALIGN_LEFT = 4, + FL_ALIGN_RIGHT = 8, + FL_ALIGN_INSIDE = 16, + FL_ALIGN_CLIP = 64, + FL_ALIGN_WRAP = 128, + FL_ALIGN_TOP_LEFT = FL_ALIGN_TOP | FL_ALIGN_LEFT, + FL_ALIGN_TOP_RIGHT = FL_ALIGN_TOP | FL_ALIGN_RIGHT, + FL_ALIGN_BOTTOM_LEFT = FL_ALIGN_BOTTOM | FL_ALIGN_LEFT, + FL_ALIGN_BOTTOM_RIGHT = FL_ALIGN_BOTTOM | FL_ALIGN_RIGHT, + FL_ALIGN_LEFT_TOP = FL_ALIGN_TOP_LEFT, + FL_ALIGN_RIGHT_TOP = FL_ALIGN_TOP_RIGHT, + FL_ALIGN_LEFT_BOTTOM = FL_ALIGN_BOTTOM_LEFT, + FL_ALIGN_RIGHT_BOTTOM = FL_ALIGN_BOTTOM_RIGHT, + FL_ALIGN_NOWRAP = 0 // for back compatability +}; + +enum Fl_Font { // standard fonts + FL_HELVETICA = 0, + FL_HELVETICA_BOLD, + FL_HELVETICA_ITALIC, + FL_HELVETICA_BOLD_ITALIC, + FL_COURIER, + FL_COURIER_BOLD, + FL_COURIER_ITALIC, + FL_COURIER_BOLD_ITALIC, + FL_TIMES, + FL_TIMES_BOLD, + FL_TIMES_ITALIC, + FL_TIMES_BOLD_ITALIC, + FL_SYMBOL, + FL_SCREEN, + FL_SCREEN_BOLD, + FL_ZAPF_DINGBATS, + + FL_FREE_FONT = 16, // first one to allocate + FL_BOLD = 1, // add this to helvetica, courier, or times + FL_ITALIC = 2 // add this to helvetica, courier, or times +}; + +#define FL_NORMAL_SIZE 14 // default size of all labels & text + +enum Fl_Color { // standard colors + FL_BLACK = 0, + FL_RED = 1, + FL_GREEN = 2, + FL_YELLOW = 3, + FL_BLUE = 4, + FL_MAGENTA = 5, + FL_CYAN = 6, + FL_WHITE = 7, + FL_INACTIVE_COLOR = 8, + FL_SELECTION_COLOR = 15, + + FL_FREE_COLOR = 16, + FL_NUM_FREE_COLOR = 16, + + FL_GRAY_RAMP = 32, + + // boxtypes limit themselves to these colors so whole ramp is not allocated: + FL_GRAY0 = 32, // 'A' + FL_DARK3 = 39, // 'H' + FL_DARK2 = 45, // 'N' + FL_DARK1 = 47, // 'P' + FL_GRAY = 49, // 'R' default color + FL_LIGHT1 = 50, // 'S' + FL_LIGHT2 = 52, // 'U' + FL_LIGHT3 = 54, // 'W' + + FL_COLOR_CUBE = 56 +}; + +inline Fl_Color inactive(Fl_Color c) {return (Fl_Color)(c|8);} +Fl_Color contrast(Fl_Color fg, Fl_Color bg); +#define FL_NUM_GRAY 24 +inline Fl_Color fl_gray_ramp(int i) {return (Fl_Color)(i+FL_GRAY_RAMP);} +#define FL_NUM_RED 5 +#define FL_NUM_GREEN 8 +#define FL_NUM_BLUE 5 +inline Fl_Color fl_color_cube(int r, int g, int b) { + return (Fl_Color)((b*FL_NUM_RED + r) * FL_NUM_GREEN + g + FL_COLOR_CUBE);} + +enum Fl_Cursor { // standard cursors + FL_CURSOR_DEFAULT = 0, + FL_CURSOR_ARROW = 35, + FL_CURSOR_CROSS = 66, + FL_CURSOR_WAIT = 76, + FL_CURSOR_INSERT = 77, + FL_CURSOR_HAND = 31, + FL_CURSOR_HELP = 47, + FL_CURSOR_MOVE = 27, + // fltk provides bitmaps for these: + FL_CURSOR_NS = 78, + FL_CURSOR_WE = 79, + FL_CURSOR_NWSE = 80, + FL_CURSOR_NESW = 81, + FL_CURSOR_NONE = 255, + // for back compatability (non MSWindows ones): + FL_CURSOR_N = 70, + FL_CURSOR_NE = 69, + FL_CURSOR_E = 49, + FL_CURSOR_SE = 8, + FL_CURSOR_S = 9, + FL_CURSOR_SW = 7, + FL_CURSOR_W = 36, + FL_CURSOR_NW = 68 + //FL_CURSOR_NS = 22, + //FL_CURSOR_WE = 55, +}; + +enum { // values for "when" passed to Fl::add_fd() + FL_READ = 1, + FL_WRITE = 4, + FL_EXCEPT = 8 +}; + +enum Fl_Mode { // visual types and Fl_Gl_Window::mode() (values match Glut) + FL_RGB = 0, + FL_INDEX = 1, + FL_SINGLE = 0, + FL_DOUBLE = 2, + FL_ACCUM = 4, + FL_ALPHA = 8, + FL_DEPTH = 16, + FL_STENCIL = 32, + FL_RGB8 = 64, + FL_MULTISAMPLE= 128 +}; + +// damage masks + +enum Fl_Damage { + FL_DAMAGE_CHILD = 0x01, + FL_DAMAGE_EXPOSE = 0x02, + FL_DAMAGE_SCROLL = 0x04, + FL_DAMAGE_OVERLAY = 0x08, + FL_DAMAGE_ALL = 0x80 +}; +</pre> +</BODY> +</HTML> diff --git a/documentation/events.html b/documentation/events.html new file mode 100644 index 000000000..b4b5f1513 --- /dev/null +++ b/documentation/events.html @@ -0,0 +1,499 @@ +<HTML> +<BODY> + +<H1 ALIGN=RIGHT>4 - Handling Events</H1> + +This chapter discusses the FLTK event model and how to handle events in your program or +widget. + +<H2>The FLTK Event Model</H2> + +<H2>Mouse Events</H2> + +<H3><TT>FL_PUSH</TT></H3> + +<H3><TT>FL_RELEASE</TT></H3> + +<H3><TT>FL_DRAG</TT></H3> + +<H3><TT>FL_MOVE</TT></H3> + +<H2>Keyboard Events</H2> + +<H3><TT>FL_KEYBOARD</TT></H3> + +<H3><TT>FL_SHORTCUT</TT></H3> + +<H2>Widget Events</H2> + +<H3><TT>FL_ACTIVATE</TT></H3> + +<H3><TT>FL_DEACTIVATE</TT></H3> + +<H3><TT>FL_HIDE</TT></H3> + +<H3><TT>FL_SHOW</TT></H3> + +<H3><TT>FL_FOCUS</TT></H3> + +<H3><TT>FL_UNFOCUS</TT></H3> + +<H3><TT>FL_ENTER</TT></H3> + +<H3><TT>FL_LEAVE</TT></H3> + +<H3><TT>FL_PASTE</TT></H3> + +<H3><TT>FL_SELECTIONCLEAR</TT></H3> + +</BODY> +</HTML> +<title>Events in Fltk</title> +<a name=types> +<h2>Events in Fltk</h2> + +<p>Events are identified the small integer argument passed to the <a +href=subclass.html#handle>Fl_Widget::handle()</a> virtual method. +Other information about the most recent event is stored in static +locations and aquired by calling <a +href=#information><code>Fl::event_*()</code></a>. This static +information remains valid until the next event is read from the X +server (that is, it is ok to look at it outside the handle() method). + +</ul><h4><code>FL_PUSH (1)</code></h4><ul> + +A mouse button has gone down with the mouse pointing at this widget. +You can find out what button by calling <a +href=#event_button>Fl::event_button()</a>. You find out the mouse +position by calling <a href=#event_x>Fl::event_x() and +Fl::event_y()</a>. + +<p>A widget indicates that it "wants" the mouse click by returning +non-zero from it's <a href=subclass.html#handle>handle()</a> method. +It will then become the <a href=#pushed>Fl::pushed()</a> widget and +will get FL_DRAG and the matching FL_RELEASE events. If handle() +returns zero then fltk will try sending the FL_PUSH to another widget. + +</ul><h4><code>FL_DRAG (5)</code></h4><ul> + +The mouse has moved with the button held down. + +</ul><h4><code>FL_RELEASE (2)</code></h4><ul> + +A mouse button has been released. You can find out what button by +calling <a href=#event_button>Fl::event_button()</a>. + +</ul><h4><code>FL_ENTER (3)</code></h4><ul> + +The mouse has been moved to point at this widget. This can be used +for highlighting feedback. If a widget wants to highlight or +otherwise track the mouse, it indicates this by returning +non-zero from it's <a href=subclass.html#handle>handle()</a> method. +It then becomes the <a href=#belowmouse>Fl::belowmouse()</a> widget +and will receive FL_MOVE and FL_EXIT events. + +</ul><h4><code>FL_MOVE (10)</code></h4><ul> + +The mouse has moved without any mouse buttons held down. This event +is sent (sort of) to the belowmouse() widget. + +</ul><h4><code>FL_LEAVE (4)</code></h4><ul> + +The mouse has moved out of the widget. + +</ul><h4><code>FL_FOCUS (6)</code></h4><ul> + +This indicates an <i>attempt</i> to give a widget the keyboard +focus. + +<p>If a widget wants the focus, it should change itself to display the +fact that it has the focus, and return non-zero from it's <a +href=subclass.html#handle>handle()</a> method. It then becomes the <a +href=#focus>Fl::focus()</a> widget and gets FL_KEYBOARD and FL_UNFOCUS +events. + +<p>The focus will change either because the window manager changed +which window gets the focus, or because the user tried to navigate +using tab, arrows, or other keys. You can check <a +href=#event_key>Fl::event_key()</a> to figure out why it moved. For +navigation it will be the key pressed, for instructions from the +window manager it will be zero. + +</ul><h4><code>FL_UNFOCUS (7)</code></h4><ul> + +Sent to the old <a href=#focus>Fl::focus()</a> when something else +gets the focus. + +</ul><h4><code>FL_KEYBOARD (8)</code></h4><ul> + +A key press. The key pressed can be found in <a +href=#event_key>Fl::event_key()</a>, or, more usefully, the text that +the key should insert can be found with <a +href=#event_text>Fl::event_text()</a> and it's length is in <a +href=#event_length>Fl::event_length()</a>. If you use the key +handle() should return 1. If you return zero then fltk assummes you +ignored the key. It will then attempt to send it to a parent widget. +If none of them want it, it will change the event into a FL_SHORTCUT +event. + +</ul><h4><code>FL_SHORTCUT (11)</code></h4><ul> + +If the <a href=#focus>Fl::focus()</a> is zero or ignores an +FL_KEYBOARD event then fltk tries sending this event to every widget +it can, until one of them returns non-zero. FL_SHORTCUT is first sent +to the belowmouse widget, then it's parents and siblings, and +eventually to every widget in the window, trying to find an object +that returns non-zero. Fltk tries real hard to not let any keystrokes +be ignored! + +<p>If the <a href=#event_text>Fl::event_text()</a> is a lower or +upper-case letter, and nothing wants the shortcut + +<p>You can also make "global" shortcuts by using <a +href=#add_handler>Fl::add_handler()</a>. A global shortcut will work +no matter what windows are displayed or which one has the focus. + +</ul><h4><code>FL_DEACTIVATE (13)</code></h4><ul> + +This widget is no longer active, due to <a +href=Fl_Widget.html#active>deactivate()</a> being called on it or one +of it's parents. active() may still be true after this, the widget is +only active if active() is true on it and all it's parents. + +</ul><h4><code>FL_ACTIVATE (14)</code></h4><ul> + +This widget is now active, due to <a +href=Fl_Widget.html#activate>active()</a> being called on it or one +of it's parents. + +</ul><h4><code>FL_HIDE (15)</code></h4><ul> + +This widget is no longer visible, due to <a +href=Fl_Widget.html#visible>hide()</a> being called, or a parent group +or window having hide() be called, or due to a parent window being +iconized. visible() may still be true after this, the widget is +visible only if visible() is true for it and all it's parents. + +</ul><h4><code>FL_SHOW (16)</code></h4><ul> + +This widget is visible again, due to <a +href=Fl_Widget.html#visible>show()</a> being called on it or one of +it's parents, or due to a parent window being deiconized. <i>Child +Fl_Windows respond to this by actually creating the X window if not +done already, so if you subclass a window, be sure to pass FL_SHOW to +the base class handle() method!</i> + +<a name=paste> +</ul><h4><code>FL_PASTE (17)</code></h4><ul> + +You should get this event some time after you call <a +href=cutpaste.html>Fl::paste()</a>. The contents of <a +href=#event_text>Fl::event_text()</a> is the text to insert and the +number of characters is in <a href=#event_length>Fl::event_length()</a>. + +</ul><h4><code>FL_SELECTIONCLEAR (18)</code></h4><ul> + +The <a href=cutpaste.html>Fl::selection_owner()</a> will get this +event before the selection is moved to another widget. This indicates +that some other widget or program has claimed the selection. + +</ul> + +<a name=information> +<h2>Fl::event_*() methods</h2> + +Fltk keeps the information about the most recent event in static +storage. This information is good until the next event is processed. +Thus it is valid inside handle() and callback() methods. + +<p>These are all trivial inline functions and thus very fast and +small. The data is stored in static locations and remains valid until +the next X event is handled. + +<a name=event_button> +</ul><h4><code>int Fl::event_button();</code></h4><ul> + +Returns which mouse button was pressed. This returns garbage if the +most recent event was not a FL_PUSH or FL_RELEASE. + +<a name=event_x> +</ul><h4><code>int Fl::event_x()</code> +<br><code>int Fl::event_y()</code></h4><ul> + +Returns the mouse position of the event (relative to the Fl_Window it +was passed to). + +</ul><h4><code>int Fl::event_x_root()</code> +<br><code>int Fl::event_y_root()</code></h4><ul> + +Returns the mouse position on the screen of the event. To find the +absolute position of an Fl_Window on the screen, use the difference +between event_x_root and event_x. + +<a name=get_mouse> +</ul><h4><code>void Fl::get_mouse(int &,int &)</code></h4><ul> + +<p>Return where the mouse is on the screen by doing a round-trip query +to the server. You should use <a +href=#event_x>Fl::event_x/y_root()</a> if possible, but this is +necessary if you are not sure if a mouse event has been processed +recently (such as to position your first window). If the display is +not open, this will open it. + +<a name=event_state> +</ul><h4><code>ulong Fl::event_state(); +<br>unsigned int Fl::event_state(int);</code></h4><ul> + +This is a bitfield of what shift states were on and what mouse buttons +were held down during the most recent event. The second version +returns non-zero if any of the passed bits are turned on. The legal +bits are <code>FL_SHIFT, FL_CAPS_LOCK, FL_CTRL, FL_ALT, FL_NUM_LOCK, +FL_META, FL_SCROLL_LOCK, FL_BUTTON1, FL_BUTTON2, FL_BUTTON3</code>. + +<i><p>X servers do not agree on shift states and FL_NUM_LOCK, FL_META, +and FL_SCROLL_LOCK may not work. The values were selected to match +the XFree86 server on Linux. In addition there is a bug in the way +Xlib works so that the shift state is not correctly reported until the +first event <b>after</b> the shift key is pressed or released.</i> + +<a name=event_key> +</ul><h4><code>int Fl::event_key(); +<br>int Fl::event_key(int); +<br>int Fl::get_key(int);</code></h4><ul> + +Fl::event_key() returns which key on the keyboard was last pushed. + +<p>Fl::event_key(int) returns true if the given key was held down (or +pressed) <i>during</i> the last event. This is constant until the +next event is read from the server. + +<p>Fl::get_key(int) returns true if the given key is held down +<i>now</i>. Under X this requires a round-trip to the server and is +<i>much</i> slower than Fl::event_key(int). + +<p>Keys are identified by the <i>unshifted</i> X keysym values. +However fltk defines a set of symbols that should work on most modern +machines for every key on the generic PC keyboard: + +<p><ul> + +<li>All keys on the main keyboard producing a printable ASCII +character use the value of that ASCII character (as though shift, +ctrl, and caps lock were not on). The space bar is 32. + +<li>All keys on the numeric keypad producing a printable ASCII +character use the value of that ASCII character plus +<code>FL_KP</code>. The highest possible value is +<code>FL_KP_Last</code> so you can range-check to see if something is +on the keypad. + +<li>All numbered function keys use the number on the function key plus +<code>FL_F</code>. The highest possible number is +<code>FL_F_Last</code>, so you can range-check a value. + +<li>Buttons on the mouse are considered keys, and use the button +number (where the left button is 1) plus <code>FL_Button</code>. + +<li>All other keys on the keypad have a symbol: <code>FL_Escape, +FL_BackSpace, FL_Tab, FL_Enter, FL_Print, FL_Scroll_Lock, FL_Pause, +FL_Insert, FL_Home, FL_Page_Up, FL_Delete, FL_End, FL_Page_Down, +FL_Left, FL_Up, FL_Right, FL_Down, FL_Shift_L, FL_Shift_R, +FL_Control_L, FL_Control_R, FL_Caps_Lock, FL_Alt_L, FL_Alt_R, +FL_Meta_L, FL_Meta_R, FL_Menu, FL_Num_Lock, FL_KP_Enter</code>. Be +careful not to confuse these with the very similar, but all-caps, +symbols used by <a href=#event_state>Fl::event_state()</a>. + +</ul> + +<p>Known bugs: on X <code>Fl::get_key(FL_Button+n)</code> does not +work. On MSWindows <code>Fl::get_key(FL_KP_Enter)</code> and +<code>Fl::event_key(FL_KP_Enter)</code> do not work. + +<a name=event_text> +</ul><h4><code>char * Fl::event_text()</code></h4><ul> + +<p>ASCII text (in the future this may be UTF-8) produced by the last +FL_KEYBOARD or FL_PASTE or possibly other event. A zero-length string +is returned for any keyboard function keys that do not produce text. +This pointer points at a static buffer and is only valid until the +next event is processed. + +<p>Under X this is the result of XLookupString. + +<a name=event_length> +</ul><h4><code>char * Fl::event_length()</code></h4><ul> + +<p>Length of the text in Fl::event_text(). There will always be a +null at this position in the text. However there may be a nul before +that if the keystroke translates to a nul character or you paste a nul +character. + +</ul><h4><code>int Fl::event_is_click()</code></h4><ul> + +Returns non-zero if the mouse has not moved far enough and not enough +time has passed since the last FL_PUSH or FL_KEYBOARD event for it +to be considered a "drag" rather than a "click". You can test this on +FL_DRAG, FL_RELEASE, and FL_MOVE events. + +</ul><h4><code>void Fl::event_is_click(0)</code></h4><ul> + +Clear the value returned by Fl::event_is_click(). Useful to prevent +the <i>next</i> click from being counted as a double-click or to make +a popup menu pick an item with a single click. Don't pass non-zero to +this. + +</ul><h4><code>int Fl::event_clicks()</code></h4><ul> + +Returns non-zero if the most recent FL_PUSH or FL_KEYBOARD was a +"double click". Returns N-1 for N clicks. A double click is counted +if the same button is pressed again while event_is_click() is true. + +</ul><h4><code>void Fl::event_clicks(int)</code></h4><ul> + +Directly set the number returned by Fl::event_clicks(). This can be +used to set it to zero so that later code does not think an item was +double-clicked. + +</ul><h4><code>int Fl::event_inside(const Fl_Widget *) const ; +<br>int Fl::event_inside(int,int,int,int);</code></h4><ul> + +Returns non-zero if the current event_x and event_y put it inside the +widget or inside an arbitrary bounding box. You should always call +this rather than doing your own comparison so you are consistent about +edge effects. + +</ul><h4><code>int Fl::test_shortcut(ulong) const ;</code></h4><ul> + +Test the current event, which must be an FL_KEYBOARD or FL_SHORTCUT, +against a shortcut value (described in <a +href=Fl_Button.html#shortcut>Fl_Button</a>). Returns non-zero if +there is a match. Not to be confused with <a +href=subclass.html#test_shortcut>Fl_Widget::test_shortcut()</a>. + +</ul> + +<a name=propagation> +<h2>Event Propagation</h2> + +<p>Fltk follows very simple and unchangeable rules for sending events. +The major innovation is that widgets can indicate (by returning 0 from +the handle() method) that they are not interested in an event, and fltk +can then send that event elsewhere. This eliminates the need for +"interests" (event masks or tables), and this is probably the main +reason fltk is much smaller than other X toolkits. + +<p>Most events are sent directly to the handle() method of the +Fl_Window that X says they belong to. The window (actually the +Fl_Group that Fl_Window is a subclass of) is responsible for sending +the events on to any child widgets. To make the Fl_Group code +somewhat easier, fltk sends some events (FL_DRAG, FL_RELEASE, +FL_KEYBOARD, FL_SHORTCUT, FL_UNFOCUS, FL_LEAVE) directly to leaf +widgets. These procedures control those leaf widgets: + +<a name=focus> +</ul><h4><code>Fl_Widget *Fl::focus() const; +<br>void Fl::focus(Fl_Widget *);</code></h4><ul> + +Get or set the widget that will receive FL_KEYBOARD events. + +<p>If you change Fl::focus(), the old one and all parents (that don't +contain the new widget) are sent FL_UNFOCUS events. Changing the +focus does <i>not</i> send FL_FOCUS to this or any widget, because +sending FL_FOCUS is supposed to <i>test</i> if the widget wants the +focus (by it returning non-zero from handle()). + +</ul><h4><code>int Fl_Widget::take_focus();</code></h4><ul> + +<p>Try to make this widget be the Fl::focus(), by first sending it an +FL_FOCUS event, and if it returns non-zero, setting Fl::focus() to +this widget. You should use this method to assign the focus to an +widget. Returns true if the widget accepted the focus. + +<a name=belowmouse> +</ul><h4><code>Fl_Widget *Fl::belowmouse() const; +<br>void Fl::belowmouse(Fl_Widget *);</code></h4><ul> + +Get or set the widget that is below the mouse. This is for +highlighting buttons. It is not used to send FL_PUSH or FL_MOVE +directly, for several obscure reasons, but those events typically go +to this widget. This is also the first widget tried for FL_SHORTCUT +events. + +<p>If you change the belowmouse widget, the old one and all parents (that +don't contain the new widget) are sent FL_LEAVE events. Changing this +does <i>not</i> send FL_ENTER to this or any widget, because +sending FL_ENTER is supposed to <i>test</i> if the widget wants the +mouse (by it returning non-zero from handle()). + +<a name=pushed> +</ul><h4><code>Fl_Widget *Fl::pushed() const; +<br>void Fl::pushed(Fl_Widget *);</code></h4><ul> + +<p>Get or set the widget that is being pushed. FL_DRAG or FL_RELEASE +(and any more FL_PUSH) events will be sent to this widget. + +<p>If you change the pushed widget, the old one and all parents (that +don't contain the new widget) are sent FL_RELEASE events. Changing +this does <i>not</i> send FL_PUSH to this or any widget, because +sending FL_PUSH is supposed to <i>test</i> if the widget wants the +mouse (by it returning non-zero from handle()). + +<a name=add_handler> +</ul><h4><code>void Fl::add_handler(int (*f)(int));</code></h4><ul> + +Install a function to parse unrecognized events. If fltk cannot figure +out what to do with an event, it calls each of these functions (most +recent first) until one of them returns non-zero. If none of them +returns non zero then the event is ignored. Events that cause this to +be called are: + +<p><ul> +<li>FL_SHORTCUT events that are not recognized by any widget. This +lets you provide global shortcut keys. + +<li>System events that fltk does not recognize. See <a +href=x.html#fl_xevent>fl_xevent</a>. + +<li><i>Some</i> other events when the widget fltk selected returns zero +from it's handle() method. Exactly which ones may change in future +versions, however. +</ul> + +<a name=modal> +</ul><h4><code>Fl_Window* Fl::modal();</code></h4><ul> + +The modal() window has it's handle() method called for all events, and +no other windows will have handle() called. If <a +href=#grab>grab()</a> has been done then this is equal to grab(). +Otherwise this is the most recently shown() window with <a +href=Fl_Window.html#modal>modal()</a> true, or null if there are no +modal() windows shown(). + +<a name=grab> +</ul><h4><code>void Fl::grab(Fl_Window&);<br> +Fl_Window* Fl::grab();</code></h4><ul> + +This is used when pop-up menu systems are active. Send all events to +the passed window no matter where the pointer or focus is (including +in other programs). The window <i>does not have to be shown()</i>, +this lets the handle() method of a "dummy" window override all event +handling and allows you to map and unmap a complex set of windows +(under both X and NT <i>some</i> window must be mapped because the +system interface needs a window id). + +<p>Fl::event_x() and y() are undefiend if the passed widget is not a +mapped Fl_Window. Use Fl::event_x_root() and Fl::event_y_root() +instead. + +<p><i>Be careful that your program does not enter an infinite loop +while grab() is on. On X this will lock up your screen!</i> + +<p>The second function returns the current grab window, or null if +none. + +<a name=release> +</ul><h4><code>void Fl::release()</code></h4><ul> + +Turn off the grab() behavior. + +</ul><p><a href = index.html>(back to contents)</a> diff --git a/documentation/filechooser.gif b/documentation/filechooser.gif Binary files differnew file mode 100644 index 000000000..44a786176 --- /dev/null +++ b/documentation/filechooser.gif diff --git a/documentation/fl_alert.gif b/documentation/fl_alert.gif Binary files differnew file mode 100644 index 000000000..6313c0774 --- /dev/null +++ b/documentation/fl_alert.gif diff --git a/documentation/fl_ask.gif b/documentation/fl_ask.gif Binary files differnew file mode 100644 index 000000000..aa999e37f --- /dev/null +++ b/documentation/fl_ask.gif diff --git a/documentation/fl_choice.gif b/documentation/fl_choice.gif Binary files differnew file mode 100644 index 000000000..9a879c841 --- /dev/null +++ b/documentation/fl_choice.gif diff --git a/documentation/fl_color_chooser.jpg b/documentation/fl_color_chooser.jpg Binary files differnew file mode 100644 index 000000000..18cde83be --- /dev/null +++ b/documentation/fl_color_chooser.jpg diff --git a/documentation/fl_input.gif b/documentation/fl_input.gif Binary files differnew file mode 100644 index 000000000..8c7ebd328 --- /dev/null +++ b/documentation/fl_input.gif diff --git a/documentation/fl_message.gif b/documentation/fl_message.gif Binary files differnew file mode 100644 index 000000000..711cd607c --- /dev/null +++ b/documentation/fl_message.gif diff --git a/documentation/fl_password.gif b/documentation/fl_password.gif Binary files differnew file mode 100644 index 000000000..6e972dee7 --- /dev/null +++ b/documentation/fl_password.gif diff --git a/documentation/fl_show_colormap.gif b/documentation/fl_show_colormap.gif Binary files differnew file mode 100644 index 000000000..5ac3f64c7 --- /dev/null +++ b/documentation/fl_show_colormap.gif diff --git a/documentation/fluid.gif b/documentation/fluid.gif Binary files differnew file mode 100644 index 000000000..99f085f36 --- /dev/null +++ b/documentation/fluid.gif diff --git a/documentation/fluid.html b/documentation/fluid.html new file mode 100644 index 000000000..47cb7d7fd --- /dev/null +++ b/documentation/fluid.html @@ -0,0 +1,894 @@ +<HTML> +<BODY> + +<H1 ALIGN=RIGHT><A NAME="fluid">6 - Programming with FLUID</A></H1> + +This chapter shows how to use the Fast Light User-Interface Designer ("FLUID") to create +your GUIs. + +<H2>What is FLUID?</H2> + +<H2>Creating A Simple Program</H2> + +<H2>Functions</H2> + +<H2>Windows</H2> + +<H2>Groups</H2> + +<H2>Tabs</H2> + +<H2>Menus</H2> + +<H2>Using Custom Widgets</H2> + +<H2>Classes</H2> + +</BODY> +</HTML> +<title>fluid Reference Manual</title> + +<center><img src=fluid.gif></center> + +<h2>What is Fluid?</h2> + +<p>Fluid (the Fast Light User Interface Designer) is a graphical +editor that is used to produce fltk source code. + +<p>Fluid edits and saves it's state in ".fl" files. These files are +text, and you could (with care) edit them in a text editor, perhaps to +get some special effects. + +<p>Fluid can "compile" the .fl file into a .C and a .H file. The .C +file defines all the objects from the .fl file and the .H file +declares all the global ones. + +<p>A simple program can be made by putting all your code (including a +main() function) into the .fl file and thus making the .C file a +single source file to compile. Normally though you write other .C +files that call the fluid functions. These .C files must #include the +.H file output (or they can #include the .C file so it still appears +to make to be a single source file). + +<pre> + _________ + / / + __________ +->/.C file /--------+ + / / / /________/ | + /.fl file /<==>[fluid]< #include | + /_________/ \ ___v_____ | + \ / / | + +>/.H file / | + /________/ | + ^ | + #include | + ___|_____ | __________ + / / V / / + / main.C /--->[c++,link]-->/ program / + /________/ /_________/ +</pre> + +<p>Normally the fluid file defines one or more "functions", which +output C++ functions. Each function defines a one or more fltk +windows, and all the widgets that go inside those windows. + +<p>Widgets created by fluid are either "named", "complex named" or +"unnamed". A named widget has a legal C++ variable identifier as it's +name (ie only alphanumeric and underscore). In this case fluid +defines a global variable that will point at the widget after the +function defining it is called. A "complex named" object has +punctuation such as '.' or '->' or any other symbols in it's name. In +this case fluid assigns a pointer to the widget to the name, but does +not attempt to declare it. This can be used to get the widgets into +structures. An "unnamed" widget has a blank name and no pointer to +them is stored. + +<p>Widgets may either call a named callback function that you write in +another source file, or you can supply a small piece of C++ source and +fluid will write a private callback function into the .C file. + +<a name=tutorial> +<h2>Worlds shortest tutorial</h2> + +<ol> + +<li>Type "fluid&" + +<li>Pick "New/code/function" off the menu. + +<li>Hit Tab, Delete to delete the function name and hit OK. This is +how you get fluid to output a "main()" function. The text "main()" +with a triangle next to it should appear highlighted in the main +window. + +<li>Pick "New/group/Window" off the menu. + +<li>Move the new window and resize it to the size you want. + +<li>Pick "New/buttons/Button" off the menu. + +<li>Hit the "OK" button to dismiss the panel that appears. + +<li>In the window you created, try moving the button by dragging it +around. Notice that it "snaps" to fixed locations. If you want to +drag it smoothly, hold down Alt. You can also change the size of the +steps with Edit/Preferences. + +<li>Try resizing the widget by dragging the edges and corners. + +<li>Type Alt+c to copy the widget. + +<li>Type Alt+v to paste a copy into the window. + +<li>Type Alt+v several times. + +<li>Drag the widgets and resize them so they don't overlap. Notice +that you have to click a widget to pick it first, then drag it. + +<li>Try selecting several widgets by dragging a box around them. Check +what happens when you move them, or when you drag an edge to resize +them. + +<li>You can also use Shift+click to toggle widgets on and off. + +<li>You can also select widgets by clicking on them in the list in the +main window, try that. + +<li>Double-click one of the widgets. You will get a control panel. + +<li>Try changing the "label". Try changing other items near the top of +the panel. To see any changes to the box type clearer, type "Alt+o" +to make the red overlay disappear. + +<li>Type "#include <stdlib.h>" into the first line of "extra code:". + +<li>Type "exit(0);" into the "callback:". + +<li>Hit OK. + +<li>Pick "File/Save As" off the menu. + +<li>Type "test.fl" into the file chooser and hit return. + +<li>Pick "File/Write Code" off the menu, hit OK on the confirmation panel. + +<li>Go back to your terminal window. Type "more test.C" and "more +test.H" and you can see the code it made. Also try "more test.fl" to +see how fluid saves it's data. + +<li>Type "make test" (you may have to add libaries to your Makefile). + +<li>Type "./test" to run your program. + +<li>Try the buttons. The one you put the code into will exit the +program. + +<li>Type "Alt+Q" to exit fluid. + +<li>Ok, now try to make a real program. + +</ol> + +<a name=running> +<h2>Running fluid</h2> + +<p>Type + +<pre> + fluid <name>.fl & +</pre> + +<p>to edit the .fl file <name>.fl. If the file does not exist you +will get an error pop-up, but if you dismiss it you will be editing a +blank setup of that name. You can run fluid without any name, in +which case you will be editing an unnamed blank setup (but you can use +save-as to write it to a file). + +<p>You can provide any of the standard fltk switches before the name: + +<pre> + -display host:n.n + -geometry WxH+X+Y + -title windowtitle + -name classname + -iconic + -fg color + -bg color + -bg2 color +</pre> + +<p>Changing the colors may be useful to see what your interface will +look at if the user calls it with the same switches. + +<p>In the current version, if you don't go into the background (with +'&') then you will be able to abort fluid by typing ^C on the terminal. +It will exit immediately, losing any changes. + +<a name=compiling> +<h2>Compiling .fl files</h2> + +<p>Fluid can also be called as a command-line "compiler" to create the +.C and .H file from a .fl file. To do this type + +<pre> + fluid -c <name>.fl +</pre> + +<p>This will read the .fl file and write <name>.C and +<name>.H (the directory will be stripped, they are written to the +current directory always), and then exit. If there are any errors +reading or writing the files it will print the error and exit with a +non-zero code. This is useful in a makefile. A line like this will +work: + +<pre> +my_panels.H my_panels.C : my_panels.fl + fluid -c my_panels.fl +</pre> + +<p>Some versions of Make will accept rules like this to allow all .fl +files found to be compiled: + +<pre> +.SUFFIXES : .fl .C .H +.fl.H : + fluid -c $< +.fl.C : + fluid -c $< +</pre> + +<p>Some versions of Make (gnumake) may prefer this syntax: + +<pre> +%.H: %.fl + fluid -c $< + +%.C: %.fl + fluid -c $< +</pre> + +<a name=browser> +<h2>The Widget Browser</h2> + +<p><img src=fluid_main.gif align = left> + +<p>The main window shows a menu bar and a scrolling browser of all the +defined widgets. The name of the .fl file being edited is shown in +the window title. + +<p>The widgets are stored in a hierarchy. You can open and close a +level by clicking the "triangle" at the left of a widget. This +widget is the <i>parent</i>, and all the widgets listed below it are it's +<i>children</i>. There can be zero children. + +<p>The top level of the hierarchy is <i>functions</i>. Each of these +will produce a single C++ public function in the output .C file. +Calling the function will create all of it's child windows. + +<p>The second level of the hierarchy is <i>windows</i>. Each of these +produces an instance of class Fl_Window. + +<p>Below that are either <i>widgets</i> (subclasses of Fl_Widget) or +<i>groups</i> of widgets (including other groups). Plain groups are +for layout, navigation, and resize purposes. <i>Tab groups</i> +provide the well-known file-card tab interface. + +<p>Widgets are shown in the browser as either their <i>name</i> (such +as "main_panel" in the example), or if <i>unnamed</i> as their +<i>type</i> and <i>label</i> (such as "Button "the green""). + +<p>You <i>select</i> widgets by clicking on their names, which +highlights them (you can also select widgets from any displayed +window). You can select many widgets by dragging the mouse across +them, or by using shift+click to toggle them on and off. To select no +widgets, click in the blank area under the last widget. Notice that +hidden children may be selected and there is no visual indication of +this. + +<p>You <i>open</i> widgets by double clicking them, or (to open several +widgets you have picked) by typing the F1 key. This will bring up a +control panel or window from which you can change the widget. + +<a name=menu> +<h2>Menu Items</h2> + +<p>The menu bar at the top is duplicated as a pop-up menu on any +displayed window. The shortcuts for all the menu items work in any +window. The menu items are: + +</ul><h4>File/Open... (Alt+Shift+O)</h4><ul> + +Discard the current editing session and read in a different .fl file. +You are asked for confirmation if you have changed the current data. + +<p>fluid can also read .fd files produced by the Forms and XForms +"fdesign" programs. It is best to read them with Merge. Fluid does not +understand everything in a .fd file, and will print a warning message +on the controlling terminal for all data it does not understand. You +will probably need to edit the resulting setup to fix these errors. +Be careful not to save the file without changing the name, as fluid +will write over the .fd file with it's own format, which fdesign +cannot read! + +</ul><h4>File/Save (Alt+s)</h4><ul> + +Write the current data to the .fl file. If the file is unnamed +(because fluid was started with no name) then ask for a file name. + +</ul><h4>File/Save As...(Alt+Shift+S)</h4><ul> + +Ask for a new name to save the file as, and save it. + +</ul><h4>File/Merge... (Alt+i)</h4><ul> + +Insert the contents of another .fl file, without changing the name of +the current .fl file. All the functions (even if they have the same +names as the current ones) are added, you will have to use cut/paste +to put the widgets where you want. + +</ul><h4>File/Write code (Alt+Shift+C)</h4><ul> + +"Compiles" the data into a .C and .H file. These are exactly the same +as the files you get when you run fluid with the -c switch. + +<p>The output file names are the same as the .fl file, with the +leading directory and trailing ".fl" stripped, and ".H" or ".C" +appended. Currently there is no way to override this. + +</ul><h4>File/Quit (Alt+q)</h4><ul> + +Exit fluid. You are asked for confirmation if you have changed the +current data. + +</ul><h4>Edit/Undo (Alt+z)</h4><ul> + +Don't you wish... This isn't implemented yet. You should do save +often so that any mistakes you make don't irretrivably destroy your +data. + +</ul><h4>Edit/Cut (Alt+x)</h4><ul> + +Delete the selected widgets and all their children. These are saved +to a "clipboard" file (/usr/tmp/cut_buffer.fl) and can be pasted back +into this fluid or any other one. + +</ul><h4>Edit/Copy (Alt+c)</h4><ul> + +Copy the selected widgets and all their children to the "clipboard" file. + +</ul><h4>Edit/Paste (Alt+c)</h4><ul> + +Paste in the widgets in the clipboard file. + +<p>If the widget is a window, it is added to whatever function is +selected, or contains the current selection. + +<p>If the widget is a normal widget, it is added to whatever window or +group is selected. If none is, it is added to the window or group +that is the parent of the current selection. + +<p>To avoid confusion, it is best to select exactly one widget before +doing a paste. + +<p>Cut/paste is the only way to change the parent of a widget. + +</ul><h4>Edit/Select All (Alt+a)</h4><ul> + +Select all widgets in the same group as the current selection. + +<p>If they are all selected already then this selects all widgets in +that group's parent. Repeatedly typing Alt+a will select larger and +larger groups of widgets until everything is selected. + +</ul><h4>Edit/Open... (F1 or double click)</h4><ul> + +If the current widget is a window and it is not displayed, display it. +Otherwise open a control panel for the most recent (and possibly all) +selected widgets. + +</ul><h4>Edit/Sort</h4><ul> + +All the selected widgets are sorted into left to right, top to bottom +order. You need to do this to make navigation keys in fltk work +correctly. You may then fine-tune the sorting with "Earlier" and +"Later". This does not affect the positions of windows or functions. + +</ul><h4>Edit/Earlier (F2)</h4><ul> + +All the selected widgets are moved one earlier in order amoung the +children of their parent (if possible). This will affect navigation +order, and if the widgets overlap it will affect how they draw, as the +later widget is drawn on top of the earlier one. You can also use +this to reorder functions and windows within functions. + +</ul><h4>Edit/Later (F3)</h4><ul> + +All the selected widgets are moved one later in order amoung the +children of their parent (if possible). + +</ul><h4>Edit/Group (F7)</h4><ul> + +Create a new Fl_Group and make all the currently selected widgets be +children of it. + +</ul><h4>Edit/Ungroup (F8)</h4><ul> + +If all the children of a group are selected, delete that group and +make them all be children of it's parent. + +</ul><h4>Edit/Overlays on/off (Alt+o)</h4><ul> + +Toggle the display of the red overlays off, without changing the +selection. This makes it easier to see box borders and how the layout +looks. The overlays will be forced back on if you change the selection. + +</ul><h4>Edit/Preferences (Alt+p)</h4><ul> + +Currently the only preferences are for the "alignment grid" that all +widgets snap to when you move them and resize them, and for the "snap" +which is how far a widget has to be dragged from it's original +position to actually change. + +</ul><h4>New/code/Function</h4><ul> + +Create a new C function. You will be asked for a name for the +function. This name should be a legal C++ function template, without +the return type. You can pass arguments, they can be referred to by +code you type into the individual widgets. + +<p>If the function contains any unnamed windows, it will be declared +as returning an Fl_Window*. The unnamed window will be returned from +it (more than one unnamed window is useless). If the function +contains only named windows it will be declared as returning void. + +<p>It is possible to make the .C output be a self-contained program +that can be compiled and executed. This is done by deleting the +function name, in which case "main(argc,argv)" is used. The function +will call show() on all the windows it creates and then call +Fl::run(). This can be used to test resize behavior or other parts of +the user interface. I'm not sure if it is possible to create really +useful programs using just Fluid. + +<p>You can change the function name by double clicking the function. + +</ul><h4>New/Window</h4><ul> + +Create a new Fl_Window. It is added to the currently selected +function, or to the function containing the currently selected item. +The window will appear, sized to 100x100. You will want to resize it +to whatever size you require. + +<p>You also get the window's control panel, which is almost exactly +the same as any other Fl_Widget, and is described in the next chapter. + +</ul><h4>New/...</h4><ul> + +All other items on the New menu are subclasses of Fl_Widget. Creating +them will add them to the currently selected group or window, or the +group or window containing the currently selected widget. The initial +dimensions and position are chosen by copying the current widget, if +possible. + +<p>When you create the widget you will get the widget's control panel, +described in the next chapter. + +</ul><h4>Help/About fluid</h4><ul> + +Pops up a panel showing the version of fluid. + +</ul><h4>Help/Manual</h4><ul> + +Not yet implemented. Use netscape to read these pages instead. + +</ul> + +<a name=widget_panel> +<h2>The Widget Panel</h2> + +When you double-click a widget or a set of widgets you will get the +"widget attribute panel": + +<p><img align = left src = fluid_widget.gif> + +<p>When you change attributes +using this panel, the changes are reflected immediately in the window. +It is useful to hit the "no overlay" button (or type Alt+o) to +hide the red overlay so you can see the widgets more accurately, +especially when setting the box type. + +<p>If you have several widgets selected, they may have different +values for the fields. In this case the value for <i>one</i> of the +widgets is shown. But if you change this value, <i>all</i> the +selected widgets are changed to the new value. + +<p>Hitting "OK" makes the changes permanent. Selecting a different +widget also makes the changes permanent. Fluid checks for simple +syntax errors in any code (such as mismatched parenthesis) before +saving any text. + +<p>"Revert" or "Cancel" put everything back to when you last brought +up the panel or hit OK. However in the current version of Fluid, +changes to "visible" attributes (such as the color, label, box) are +not undone by revert or cancel. Changes to code like the callbacks +is undone, however. + +<a name=widget_attributes> +<h2>Widget Attributes</h2> + +</ul><h4>Name (text field)</h4><ul> + +Name of a global C variable to declare, and to store a pointer to this +widget into. This variable will be of type "<class>*". If the name +is blank then no variable is created. + +<p>You can name several widgets with "name[0]", "name[1]", "name[2]", +etc. This will cause Fluid to declare an array of pointers. The +array is big enough that the highest number found can be stored. All +widgets that in the array must be the same type. + +</ul><h4>Type (upper-right pulldown menu)</h4><ul> + +Some classes have subtypes that modify their appearance or behavior. +You pick the subtype off of this menu. + +</ul><h4>Box (pulldown menu)</h4><ul> + +The boxtype to draw as a background for the widget. + +<p>Many widgets will work, and draw faster, with a "frame" instead of +a "box". A frame does not draw the colored interior, leaving whatever +was already there visible. Be careful, as fluid may draw this ok but +the real program leave unwanted stuff inside the widget. + +<p>If a window is filled with child widgets, you can speed up +redrawing by changing the window's box type to "NO_BOX". Fluid will +display a checkerboard for any areas that are not colored in by boxes +(notice that this checkerboard is not drawn by the resulting program, +instead random garbage is left there). + +</ul><h4>Color</h4><ul> + +<p>The color to draw the box with. + +</ul><h4>Color2</h4><ul> + +<p>Some widgets will use this color for certain parts. Fluid does not +always show the result of this: this is the color buttons draw in when +pushed down, and the color of input fields when they have the focus. + +</ul><h4>Label</h4><ul> + +String to print next to or inside the button. + +<p>You can put newlines into the string to make multiple lines, the +easiest way is by typing ctrl+j. + +</ul><h4>Label style (pull down menu)</h4><ul> + +How to draw the label. Normal, shadowned, engraved, and embossed +change the appearance of the text. "symbol" requires the label to +start with an '@' sign to draw a named <a +href=Labeltypes.html#symbols>symbol</a>. + +<p>From this menu you can also pick <a +href=#images>"Image..."</a>. This lets you use the contents +of an image file (currently an xpm pixmap or xbm bitmap) to label the +widget. + +</ul><h4>Label alignement (buttons)</h4><ul> + +Where to draw the label. The arrows put it on that side of the +widget, you can combine the to put it in the corner. The "box" button +puts the label inside the widget, rather than outside. + +</ul><h4>Label font</h4><ul> + +Font to draw the label in. Ignored by symbols, bitmaps, and pixmaps. +Your program can change the actual font used by these "slots", in case +you want some font other than the 16 provided. + +</ul><h4>Label size</h4><ul> + +Point size for the font to draw the label in. Ignored by symbols, +bitmaps, and pixmaps. To see the result without dismissing the panel, +type the new number and then Tab. + +</ul><h4>Label color</h4><ul> + +Color to draw the label. Ignored by pixmaps (bitmaps, however, do use +this color as the foreground color). + +</ul><h4>Text font, size, color</h4><ul> + +Some widgets display text, such as input fields, pull-down menus, +browsers. You can change this here. + +</ul><h4>Visible</h4><ul> + +If you turn this off the widget is hidden initially. Don't change +this for windows or for the immediate children of a Tabs group. + +</ul><h4>Active</h4><ul> + +If you turn this off the widget is deactivated initially. Currently +no fltk widgets display the fact that they are inactive (like by graying +out), but this may change in the future. + +</ul><h4>Resizable</h4><ul> + +If a window is resizable or has an immediate child that is resizable, +then the user will be able to resize it. In addition all the size +changes of a window or group will go "into" the resizable child. If +you have a large data display surrounded by buttons, you probably want +that data area to be resizable. + +<p>Only one child can be resizable. Turning this on turns it off for +other children. + +<p>You can get more complex behavior by making invisible boxes the +resizable widget, or by using hierarchies of groups. Unfortunatley +the only way to test it is to compile the program. Resizing the fluid +window is <i>not</i> the same as what will happen in the user program. + +</ul><h4>Hotspot</h4><ul> + +Each window may have exactly one hotspot (turning this on will turn +off any others). This will cause it to be positioned with that widget +centered on the mouse. This position is determined <i>when the fluid +function is called, so you should call it immediately before showing +the window</i>. If you want the window to hide and then reappear at a +new position, you should have your program set the hotspot itself just +before show(). + +</ul><h4>subclass</h4><ul> + +This is how you put your own subclasses of Fl_Widget in. Whatever +identifier you type in here will be the class that is instantiated. + +<p>In addition, no #include header file is put in the .H file. You +must provide a #include line as the first of the "extra code" which +declares your subclass. + +<p>The class had better be similar to the class you are spoofing. It +does not have to be a subclass. It is sometimes useful to change this +to another fltk class: currently the only way to get a double-buffered +window is to change this field for the window to "Fl_Double_Window" +and to add "#include <FL/Fl_Double_Window.H>" to the extra code. + +</ul><h4>Extra code</h4><ul> + +These four fields let you type in literal lines of code to dump into +the .H or .C files. + +<p>If the text starts with a '#' or the word "extern" then fluid +thinks this is an "include" line, and it is written to the .H file. +If the same include line occurs several times then only one copy is +written. + +<p>All other lines are "code" lines. The widget being constructed is +pointed to by the local variable 'o'. The window being constructed is +pointed to by the local variable 'w'. You can also access any +arguments passed to the function here, and any named widgets that are +before this one. + +<p>Fluid will check for matching parenthesis, braces, and quotes, but +does not do much other error checking. Be careful here, as it may be +hard to figure out what widget is producing an error in the compiler. +If you need more than 4 lines you probably should call a function in +your own .C code. + +</ul><h4>Callback</h4><ul> + +This can either be the name of a function, or a small snippet of +code. Fluid thinks that if there is any punctuation then it is code. + +<p>A name names a function in your own code. It must be declared as +"void <name>(<class>*,void*)". + +<p>A code snippet is inserted into a static function in the .C output +file. The function prototype is +"void f(<class>* o, void* v)", so you can refer to +the widget as 'o' and the user_data as 'v'. Fluid will check for +matching parenthesis, braces, and quotes, but does not do much other +error checking. Be careful here, as it may be hard to figure out what +widget is producing an error in the compiler. + +<p>If the callback is blank then no callback is set. + +</ul><h4>user_data</h4><ul> + +<p>This is a value for the user_data() of the widget. If blank the +default value of zero is used. This can be any piece of C code that +can be put "(void*)(<here>)". + +</ul><h4>User data type</h4><ul> + +The "void*" in the callback function prototypes is replaced with +this. You may want to use "long" for old XForms code. Be warned that +anything other than "void*" is not guaranteed to work by the C++ spec! +However on most architectures other pointer types are ok, and long is +usually ok. + +</ul><h4>When</h4><ul> + +When to do the callback. Can be "never", "changed", "release". The +value of "enter key" is only useful for text input fields. The "no +change" button means the callback is done on the matching event even +if the data is not changed. + +<p>There are rare but useful other values for the when() field that +are not in the menu. You should use the extra code fields to put +these values in. + +</ul> + +<a name=windows> +<h2>Selecting & Moving Widgets</h2> + +<p>Double-clicking a window name in the browser will display it, if +not displayed yet. From this display you can select widgets, sets of +widgets, and move or resize them. To close a window either +double-click it or type Esc. + +<p>To select a widget, click it. To select several widgets drag a +rectangle around them. Holding down shift will toggle the selection +of the widgets instead. + +<p>You cannot pick hidden widgets. You also cannot choose some +widgets if they are completely overlapped by later widgets. Use the +browser to select these widgets. + +<p>The selected widgets are shown with a red "overlay" line around +them. You can move the widgets by dragging this box. Or you can +resize them by dragging the outer edges and corners. Hold down the +Alt key while dragging the mouse to defeat the snap-to-grid effect for +fine positioning. + +<p>If there is a tab box displayed you can change which child is +visible by clicking on the file tabs. The child you pick is +selected. + +<p>The arrow, tab, and shift+tab keys "navigate" the selection. Left, +right, tab, or shift+tab move to the next or previous widgets in the +hierarchy. Hit the right arrow enough and you will select every +widget in the window. Up/down widgets move to the previous/next +widgets that overlap horizontally. If the navigation does not seem to +work you probably need to "Sort" the widgets. This is important if +you have input fields, as fltk uses the same rules when using arrow keys +to move between input fields. + +<p>To "open" a widget, double click it. To open several widgets +select them and then type F1 or pick "Edit/Open" off the pop-up menu. + +<p>Type Alt+o to temporarily toggle the overlay off without changing +the selection, so you can see the widget borders. + +<p>You can resize the window by using the window manager border +controls. Fltk will attempt to round the window size to the nearest +multiple of the grid size and makes it big enough to contain all the +widgets (it does this using illegal X methods, so it is possible it +will barf with some window managers!). Notice that the actual window +in your program may not be resizable, and if it is, the effect on +child widgets may be different. + +<p>The panel for the window (which you get by double-clicking it) is +almost identical to the panel for any other Fl_Widget. There are +three extra items: + +</ul><h4>Border</h4><ul> + +This button turns the window manager border on or off. On most window +managers you will have to close the window and reopen it to see the +effect. + +</ul><h4>xclass</h4><ul> + +The string typed into here is passed to the X window manager as the +class. This can change the icon or window decorations. On most +(all?) window managers you will have to close the window and reopen it +to see the effect. + +</ul> + +<a name=images> +<h2>Image Labels</h2> + +<p>Selecting "Image..." off the label style pull-down menu will bring +up a file chooser from which you pick the image file. If an image has +already been chosen, you can change the image used by picking +"Image..." again. The name of the image will appear in the "label" +field, but you can't edit it. + +<p>The <i>contents</i> of the image file are written to the .C file, +so if you wish to distribute the C code, you only need to copy the .C +file, not the images. If many widgets share the same image then only +one copy is written. + +<p>However the <i>file name</i> is stored in the .fl file, so to read +the .fl file you need the image files as well. Filenames are relative +to the location the .fl file is (not necessarily the current +directory). I recommend you either put the images in the same +directory as the .fl file, or use absolute path names. + +</ul><h4>Notes for all image types</h4><ul> + +<p>Fluid runs using the default visual of your X server. This may be +8 bits, which will give you dithered images. You may get better +results in your actual program by adding the code "Fl::visual(FL_RGB)" +to your code right before the first window is displayed. + +<p>All widgets with the same image on them share the same code and +source X pixmap. Thus once you have put an image on a widget, it is +nearly free to put the same image on many other widgets. + +<p>If you are using a painting program to edit an image: the only way +to convince Fluid to read the image file again is to remove the image +from all widgets that are using it (including ones in closed windows), +which will cause it to free it's internal copy, and then set the image +again. You may find it easier to exit Fluid and run it again. + +<p>Don't rely on how fltk crops images that are outside the widget, as +this may change in future versions! The cropping of inside labels +will probably be unchanged. + +<p>To more accurately place images, make a new "box" widget and put +the image in that as the label. This is also how you can put both an +image and text label on the same widget. If your widget is a button, +and you want the image inside it, you must change the button's boxtype +to FL_UP_FRAME (or another frame), otherwise when it is pushed it will +erase the image. + +</ul><h4>XBM (X bitmap files)</h4><ul> + +<p>Fluid will read X bitmap files. These files have C source code to +define a bitmap. Sometimes they are stored with the ".h" or ".bm" +extension rather than the standard ".xbm". + +<p>Fluid will output code to construct an Fl_Bitmap widget and use it +to label the widget. The '1' bits in the bitmap are drawn using the +label color of the widget. You can change the color in Fluid. The +'0' bits are transparent. + +<p>The program "bitmap" on the X distribution does an ok job of +editing bitmaps. + +</ul><h4>XPM (X pixmap files)</h4><ul> + +<p>Fluid will read X pixmap files as used by the libxpm library. +These files have C source code to define a pixmap. The filenames +usually have a ".xpm" extension. + +<p>Fluid will output code to construct an Fl_Pixmap widget and use it +to label the widget. The label color of the widget is ignored, even +for 2-color images that could be a bitmap. + +<p>XPM files can mark a single color as being transparent. Currently +fltk and Fluid simulate this transparency rather badly. It will use the +color() of the widget as the background, and all widgets using the +same pixmap are assummed to have the same color. This may be fixed in +the future or on non-X systems. + +<p>I have not found any good editors for small iconic pictures. For +pixmaps I have used <a +href=http://www.danbbs.dk/~torsten/xpaint/index.html>XPaint</a>. This +(and most other) painting programs are designed for large full color +images and are difficult to use to edit an image of small size and few +colors. + +</ul><h4>GIF files</h4><ul> + +<p>Fluid will also read GIF image files. These files are often used +on html documents to make icons. This lets you use nice icons that +you steal off the net in your user interface. + +<p>Fluid converts these into <a href=xpm.html>(modified)</a> xpm +format and uses an Fl_Pixmap widget to label the widget. Transparency +is handled the same as for xpm files. Notice that the conversion +removes the compression, so the code may be much bigger than the .gif +file. Only the first image of an animated gif file is used. + +<p>Behavior and performance with large .gif files is not guaranteed! + +</ul> + +<p><a href = index.html>(back to contents)</a> diff --git a/documentation/fluid_main.gif b/documentation/fluid_main.gif Binary files differnew file mode 100644 index 000000000..ab72873c5 --- /dev/null +++ b/documentation/fluid_main.gif diff --git a/documentation/fluid_widget.gif b/documentation/fluid_widget.gif Binary files differnew file mode 100644 index 000000000..5c9964f0c --- /dev/null +++ b/documentation/fluid_widget.gif diff --git a/documentation/forms.html b/documentation/forms.html new file mode 100644 index 000000000..1d6614581 --- /dev/null +++ b/documentation/forms.html @@ -0,0 +1,230 @@ +<HTML> +<BODY> + +<H1 ALIGN=RIGHT><A NAME="forms">E - Forms Compatibility</A></H1> + +<a href="#fluid">Fluid</a> (the Fast Light User Interface Designer) +can read the .fd files put out by all versions of Forms and XForms +fdesign. However, it will mangle them a bit, but it prints a warning +message about anything it does not understand. Fluid cannot write +fdesign files, so you should save to a new name so you don't write +over the old one. + +<p>You will need to edit your main code considerably to get it to link +with the output from fluid. If you are not interested in this you may +have more immediate luck with the forms compatability header, +<tt><FL/forms.H></tt>. + +<p>You should be able to compile existing Forms or XForms source code +by changing the -I switch to your compiler so that the forms.h file +supplied with FLTK is included. Take a look at forms.h to see how it +works, but the basic trick is lots of inline functions. +Most of the XForms demo programs work without changes. + +<p>Although FLTK was designed to be compatable with the GL Forms library +(version 0.3 or so), XForms has bloated severely and it's interface is +X specific. Therefore, XForms compatability is no longer a goal of +FLTK. Compatability was limited to things that were free, or that +would add code that would not be linked in if the feature is unused. +I did not add anything that would make the FLTK widgets bigger, or that +used X types as arguments. + +<p>To use any new features of FLTK, you should rewrite your code to not +use the inline functions and instead use "pure" FLTK. This +will make it a lot cleaner and make it easier to figure out how to +call the FLTK functions. Unfortunately this conversion is harder than I +expeceted and even our inhouse code still uses forms.H a lot. + +<h2>Problems you will encounter</h2> + +<ul> + +<p><li>Many parts of XForms use X-specific structures like XEvent in +their interface. I did not emulate these! Unfortunately these +features (such as the "canvas" widget) are needed by most large +programs. You will need to rewrite these to use FLTK subclasses. + +<p><li><a href=Fl_Free.html>Fl_Free</a> widgets emulate the <i>old</i> +Forms "free" widget. It may be useful for porting programs that +change the handle() function on widgets, but you will still need to +rewrite things. + +<P><li><a href=Fl_Timer.html>Fl_Timer</a> widgets are provided to +emulate the XForms timer. These work, but are quite inefficient +and inaccurate compared to using Fl::add_timeout(). + +<p><li><i>All instance variables are hidden.</i> +If you directly refer to the x, y, w, h, label, or other fields of +your Forms widgets you will have to add empty parenthesis after each +reference. The easiest way to do this is to globally replace "->x" +with "->x()", etc. Replace "boxtype" with box(). + +<p><li>const char* arguments to most FLTK methods are simply stored, while +Forms would strdup() the passed string. This is most noticable with the +label of widgets. Your program must always pass static data such as a +string constant or malloc'd buffer to label(). If you are using +labels to display program output you may want to try the <a +href=Fl_Output.html>Fl_Output</a> widget. + +<p><li>The default fonts and sizes are matched to the older GL version of +Forms, so all labels will draw somewhat larger than an XForms program +does. + +<p><li>fdesign outputs a setting of a "fdui" instance variable to the main +window. I did not emulate this because I wanted all instance +variables to be hidden. You can store the same information in the +user_data() field of a window. To do this, +search through the fdesign output for all occurances +of "->fdui" and edit to use "->user_data()" instead. This will +require casts and is not trivial. + +<p><li>The prototype for the functions passed to fl_add_timeout() and +fl_set_idle_callback() callback are different. + +<p><li><b>All the following XForms calls are missing:</b><p> + +<li><code>FL_VERSION, FL_REVISION</code>, fl_library_version() +<li><code>FL_RETURN_DBLCLICK</code> (use Fl::event_clicks()) +<li>fl_add_signal_callback() +<li>fl_set_form_atactivate() & fl_set_form_atdeactivate() +<li>fl_set_form_property() +<li>fl_set_app_mainform(), fl_get_app_mainform() +<li>fl_set_form_minsize(), fl_set_form_maxsize() +<li>fl_set_form_event_cmask(), fl_get_form_event_cmask() +<li>fl_set_form_dblbuffer(), fl_set_object_dblbuffer() (use an +Fl_Double_Window instead) +<li>fl_adjust_form_size() +<li>fl_register_raw_callback() +<li>fl_set_object_bw(), fl_set_border_width() +<li>fl_set_object_resize(), fl_set_object_gravity() +<li>fl_set_object_shortcutkey() +<li>fl_set_object_automatic() +<li>fl_get_object_bbox() (maybe FLTK should do this) +<li>fl_set_object_prehandler(), fl_set_object_posthandler() +<li>fl_enumerate_fonts() +<li>Most drawing functions +<li>fl_set_coordunit() (FLTK uses pixels all the time) +<li>fl_ringbell() +<li>fl_gettime() +<li>fl_win*() (all these functions) +<li>fl_initialize(argc,argv,x,y,z) ignores last 3 arguments +<li>fl_read_bitmapfile(), fl_read_pixmapfile() +<li>fl_addto_browser_chars() +<li>FL_MENU_BUTTON just draws normally +<li>fl_set_bitmapbutton_file(), fl_set_pixmapbutton_file() +<li>FL_CANVAS objects +<li>FL_DIGITAL_CLOCK (comes out analog) +<li>fl_create_bitmap_cursor(), fl_set_cursor_color() +<li>fl_set_dial_angles() +<li>fl_show_oneliner() +<li>fl_set_choice_shortcut(a,b,c) +<li>command log +<li>Only some of file selector is emulated +<li>FL_DATE_INPUT +<li>fl_pup*() (all these functions) +<li>textbox object (should be easy but I had no sample programs) +<li>xyplot object +</ul> + +<h2>Additional notes for porting old Forms programs</h2> + +<p>These notes were written for porting programs written with the +older GL version of Forms. Most of these problems are the same ones +encountered when going from old Forms to XForms: + +<h4>Does not go into background</h4> + +The GL library always forked when you created the first window, unless +"foreground()" was called. FLTK acts like "foreground()" is called all +the time. If you really want the fork behavior do "if (fork()) +exit(0)" right at the start of your program. + +<h4>You cannot use GL windows or fl_queue</h4> + +<P>If a Forms (not XForms) program if you wanted your own window for +displaying things you would create a GL window and draw in it, +periodically calling Forms to check if the user hit buttons on the +panels. If the user did things to the GL window, you would find this +out by having the value FL_EVENT returned from the call to Forms. + +<p>None of this works with FLTK. Nor will it compile, the necessary +calls are not in the interface. + +<p>You have to make a subclass of <a +href=Fl_Gl_Window.html>Fl_Gl_Window</a> and write a draw() method and +handle() method. This may require anywhere from a trivial to a major +rewrite. See the example program <a href=shape.C.html>shape.C</a> for +how this is structured. + +<p>If you draw into the overlay planes you will have to also write a +draw_overlay() routine and call redraw_overlay() on the gl window. + +<p>One easy way to hack your program so it works is to make the draw() +and handle() methods on your window set some static variables, storing +what event happened. Then in the main loop of your program, call +Fl::wait() and then check these variables, acting on them as +though they are events read from fl_queue. + +<h4>You must use OpenGL to draw everything</h4> + +<p>The file <FL/gl.h> defines replacements for a lot of gl calls, +translating them to OpenGL. There are much better translators +available that you might want to investigate. + +<h4>You cannot make Forms subclasses</h4> + +Programs that call fl_make_object or directly setting the handle +routine will not compile. You have to rewrite them to use a subclass +of Fl_Widget. It is important to note that the handle() method is not +exactly the same as the handle() function of Forms. Where a Forms +handle() returned non-zero, your handle() must call do_callback(). +And your handle() must return non-zero if it "understood" the event. + +<p>An attempt has been made to emulate the "free" widget. This +appears to work quite well. It may be quicker to modify your subclass +into a "free" widget, since the "handle" functions match. + +<p>If your subclass draws into the overlay you are in trouble and will +have to rewrite things a lot. + +<h4>You cannot use <device.h></h4> + +If you have written your own "free" widgets you will probably get a +lot of errors about "getvaluator". You should substitute: + +<table> +<tr><td align=center>Forms <td align=center>FLTK +<tr><td>MOUSE_X <td>Fl::event_x_root() +<tr><td>MOUSE_Y<td> Fl::event_y_root() +<tr><td>LEFTSHIFTKEY,RIGHTSHIFTKEY<td> Fl::event_shift() +<tr><td>CAPSLOCKKEY<td> Fl::event_capslock() +<tr><td>LEFTCTRLKEY,RIGHTCTRLKEY<td> Fl::event_ctrl() +<tr><td>LEFTALTKEY,RIGHTALTKEY<td> Fl::event_alt() +<tr><td>MOUSE1,RIGHTMOUSE<td> Fl::event_state()&(1<<10) +<tr><td>MOUSE2,MIDDLEMOUSE<td> Fl::event_state()&(1<<9) +<tr><td>MOUSE3,LEFTMOUSE<td> Fl::event_state()&(1<<8) +</table> + +<p>Anything else in getvaluator and you are on your own... + +<h4>Font numbers are different</h4> + +The "style" numbers have been changed because I wanted to insert +bold-italic versions of the normal fonts. If you use Times, Courier, +or Bookman to display any text you will get a different font out of +FLTK. If you are really desperate to fix this use the following code:<ul> + +<pre> +fl_font_name(3,"*courier-medium-r-no*"); +fl_font_name(4,"*courier-bold-r-no*"); +fl_font_name(5,"*courier-medium-o-no*"); +fl_font_name(6,"*times-medium-r-no*"); +fl_font_name(7,"*times-bold-r-no*"); +fl_font_name(8,"*times-medium-i-no*"); +fl_font_name(9,"*bookman-light-r-no*"); +fl_font_name(10,"*bookman-demi-r-no*"); +fl_font_name(11,"*bookman-light-i-no*"); +</pre></ul> + +</BODY> +</HTML> diff --git a/documentation/functions.html b/documentation/functions.html new file mode 100644 index 000000000..6dfe9a0cf --- /dev/null +++ b/documentation/functions.html @@ -0,0 +1,768 @@ +<HTML> +<BODY> + +<H1 ALIGN=RIGHT>B - Function Reference</H1> + +When we created the window and box widgets + and widgets inside the window. + Here a single +<a href=Fl_Box.html>Fl_Box</a> is created. The arguments to the +constructor are a value for the <a href=Fl_Widget.html#box>box()</a> +property (most constructors do not have this), values for <a +href=Fl_Widget.html#xywh>x(), y(), w(), h()</a> to define the position +and size of the box, and a value for <a +href=Fl_Widget.html#label>label()</a> to define the text printed in the +box. + +<p>All the widgets have several attributes and there is a method for +setting and getting the current value of each of them. +<Code>box->labelsize(36)</tt> sets the <a +href=Fl_Widget.html#labelsize>labelsize()</a> to 36. You could get +the value with <tt>box->labelsize()</tt>. Often you have to set +many properties, so you will be relieved to know that almost all of +these methods are trivial inline functions. + +<P><a href=Fl_Widget.html#labelfont><tt>labelfont()</tt></a> is +set to a symbolic value which is compiled into a constant integer, 3 +in this case. All properties that cannot be described by a single +small number use a 1-byte index into a table. This makes the widget +smaller, allows the actual definition of the property to be deferred +until first use, and you can redefine existing entries to make global +style changes. + +<p><a +href=Fl_Widget.html#labeltype><tt>labeltype(FL_SHADOW_LABEL)</tt></a> +also stores a 1-byte symbolic value, in this case indicating a +procedure to draw drop shadows under the letters should be called to +draw the label. + +<p>The constructor for widgets adds them as children of the "current +group" (usually a window). <tt>window->end()</tt> stops adding +them to this window. For more control over the construction of +objects, you can end() the window immediately, and then add the +objects with <a +href=Fl_Group.html#add><tt>window->add(box)</tt></a>. You can +also do <a href=Fl_Group.html#begin><tt>window->begin()</tt></a> +to switch what window new objects are added to. + +<p><a href=Fl_Window.html#show><Code>window->show()</tt></a> finally +puts the window on the screen. It is not until this point that the X +server is opened. FLTK provides some <i>optional</i> and rather +simple command-line parsing if you call <a +href=Fl.html#show>show(argv,argc)</a>. If you don't want this, just +call show() with no arguments, and <i>the unused argument code is not +linked into your program, making it smaller!</i> + +<p><a href=Fl.html#run><tt>Fl::run()</tt></a> makes FLTK +enter a loop to update the screen and respond to events. By +default when the user closes the last window FLTK exits by calling <a +href=Fl.html><tt>exit(0)</tt></a>. <i>run() does not +actually return, it is declared to return an int so you can end your +main() function with "return Fl::run()" and outwit the stupid compiler +made by a certain very large software company.</i> + +<p>The following command compiles this program, assuming the FLTK +library has been put in /usr/local/lib and the header files in +/usr/local/include/FL: + + + + + + + + + + + + + + + + + + + + + + +<p>The first thing your program should do is construct one or more +trees of <tt>Fl_Widgets</tt>. The base widget of each of these is +an <tt>Fl_Window</tt> widget. The constructors for widgets +automatically add them as children of the most recent created window +widget (use window->end() to stop this). Constructing the widgets +<i>does not require the display to be open and does not open it</i>, +unless you purposely open it to get information such as the width of a +font. + +<p><tt>Fl_Window</tt>s are displayed on the screen with +<tt>Fl_Window::show()</tt>. For the first window you may also use +<tt>Fl_Window::show(argc,argv)</tt> and FLTK will automatically +parse some startup arguments such as -display. + +<p>Then the program repeatedly calls <tt>Fl::wait()</tt>. Each +time "something happens" <tt>Fl::wait()</tt> returns, usually after +a block of X events have been read and processed. It is often useful +for a program to check global state after each event, and FLTK makes +this easy by leaving the main loop under your control. + +<p>Each widget has a <i>single</i> "callback". This is a function that +is called when something happens (such as the user pressing a button). +FLTK avoids all the complexities of signals/slots by having only a +single callback. Instead a when() method on the object selects when +the callback is done (ie. when a slider is moved or when the mouse is +released). + +<p>The callback is passed a pointer to the widget and a void* user_data +field. This is redundant, as the user_data can be determined from the +widget, but was done for XForms compatability and to make the same +callbacks useful for menu items. Typically you want to turn the +callback into a method on some C++ object. A simple way is to use the +user_data as a pointer to the object. A more common but harder to +understand way is to store the object in the <i>parent</i> widget's +user_data field, since usually all the controls on a window are for the +same object, this lets you use the user_data for an abitrary method +argument. + +<p>To display graphic data, you must <i>subclass</i> either +<tt>Fl_Window</tt> or <tt>Fl_Widget</tt> and define the virtual +<tt>draw()</tt> method. This can use functions defined in +<FL/fl_draw.H>, or can use system-specific calls such as Xlib. If +the data being displayed changes, your main program calls the +<tt>redraw()</tt> method on your widget, and FLTK will call +<tt>draw()</tt> while waiting for the next event. Subclassing +<tt>Fl_Window</tt> or <tt>Fl_Widget</tt> is so easy that I felt +it unnecessary to provide the "canvas" widget that most toolkits have. + +<p>If your program needs to monitor another device (such as stdin) you +can provide a callback routine for when it becomes ready, by using +<tt>Fl::add_fd(i)</tt>. If your program needs something to happen +at regular intervals you can define a timeout callback with <tt><a +href=Fl.html#add_timeout>Fl::add_timeout(time)</a></tt>. + +<p>Building a large hierarchy is made much easier with <i>fluid</i> +(the Fast Light User Interface Designer). This is a program that lets +you interactively design the widget layout and set all the properties +visually. It outputs C++ source code that you compile and link with +your program. All you have to write is the main loop and any +callbacks. + +</BODY> +</HTML> +<HTML> +<BODY> + +This chapter demonstrates the basics of FLTK programming with examples. + +<H2>Compiling a FLTK Program</H2> + +<H3>Include Files</H3> + +<H3>Library Files</H3> + +<H2>A "Hello, World" Program</H2> + +<H3>Creating the Window</H3> + +<H3>The Main Loop</H3> + +</BODY> +</HTML> +<title>FLTK example: ask.C</title> +<h2>ask.C</h2> + +<p><img src = ask.C.gif align=top> + +<pre> +#include <stdio.h> +#include <string.h> +#include <FL/Fl.H> +#include <FL/Fl_Window.H> +#include <FL/Fl_Input.H> +#include <FL/Fl_Button.H> +#include <FL/Fl_Return_Button.H> + +int get_string(char*buffer, const char *from) { + Fl_Window window(320,75); + window.set_modal(); + Fl_Input input(60, 40, 250, 25,"Input:"); + input.value(buffer); + Fl_Button cancel(60, 10,80, 25,"cancel"); + Fl_Return_Button ok(150, 10,80, 25,"OK"); + window.end(); + window.show(); + for (;;) { + Fl::wait(); + Fl_Widget *o; + while (o = Fl::readqueue()) { + if (o == &ok) { + strcpy(buffer, input.value()); + return 1; + } else if (o == &cancel || o == &window) { + return 0; + } + } + } +} + +int main(int argc, char **argv) { + char buffer[128]; + if (get_string(buffer, argv[1])) { + puts(buffer); + return 0; + } else { + return 1; // exit with error + } +} +</pre> + +<p>Widgets don't need to have <a +href=Fl_Widget.html#callback>callback()</a> set. The <a +href=Fl_Widget.html#default_callback>default callback</a> puts a +pointer to the widget on a "queue" from which it can later be read +with <a href=Fl.html#readqueue>Fl::readqueue()</a>. This was +done for Forms compatibility but it is useful for <a +href=Fl_Window.html#modal>modal windows</a>. In this example the +"get_string" function puts up a modal window and loops until one of +the buttons is pushed. + +<a href=Fl.html#wait>Fl::wait()</a> does exactly one cycle of +what Fl::run() does repeatedly: it updates the screen and then waits +for and responds to an event (or several events if they are all ready +at the same time). It then returns, allowing the user program to +check any state information it wants to after each group of events. +One thing the user program can check is <a +href=Fl.html#readqueue>Fl::readqueue()</a> which returns each +object without a callback that was triggered. It returns null when +the queue is empty. It is possible for more than one object to be on +the queue (or the same object several times) so if your program wants +to read the queue it should always read it until empty and ignore +unrecognized widgets (don't look at them as they may have been +deleted). + +<P><a href=Fl_Window.html#modal>modal()</a> on a window prevents any +interaction with other program windows below it, and prevents the user +from raising a program window above it (well, it tries, but X is +broken). It won't make any difference in this program because there +is only one window, but this allows the "get_string" function to be +used as subroutine by a larger program and have the expected behavior. + +<P>This program also demonstrates that FLTK widgets may be constructed +as C++ automatic objects (local variables). You have to be careful +about <a href=Fl_Widget.html#destructor>destruction</a>, however. +Always make sure all automatic children are destructed before the +container (by declaring the children <i>after</i> the container), +since the destructor for a container will attempt to delete all +remaining children, and you don't want to delete automatic objects. + +<p><a href = shape.C.html>[Next example]</a> +<br><a href = index.html>[back to contents]</a> +<title>FLTK example: button.C</title> +<h2>button.C</h2> + +<p><img src= button.C.gif align=top> + +<pre> +#include <stdlib.h> +#include <stdio.h> +#include <FL/Fl.H> +#include <FL/Fl_Window.H> +#include <FL/Fl_Button.H> + +void beepcb(Fl_Widget *, void *) { + printf("\007"); fflush(stdout); +} + +void exitcb(Fl_Widget *, void *) { + exit(0); +} + +int main(int argc, char ** argv) { + Fl_Window *window = new Fl_Window(320,65); + window->begin(); + Fl_Button *b1 = new Fl_Button(20, 20, 80, 25, "Beep"); + b1->callback(beepcb,0); + Fl_Button *b2 = new Fl_Button(120,20, 80, 25, "no op"); + Fl_Button *b3 = new Fl_Button(220,20, 80, 25, "Exit"); + b3->callback(exitcb,0); + window->end(); + window->show(argc,argv); + return Fl::run(); +} +</pre> + +<p>In this example we make some button widgets and make them do +something through callbacks. + +<P>All widgets have a single <a +href=Fl_Widget.html#callback>callback()</a> function. It is called in +response to an event on that widget, exactly which event depends on +the type of widget. The function takes two arguments: a pointer to +the widget (you will usually need to cast this to the correct +subclass) and a void* pointer to a piece of arbitrary user_data. + +<P>You don't have to give all the widgets a callback, as the "no op" b2 +widget demonstrates. What these do is described in the next program. + +<p><a href = ask.C.html>[Next example]</a> +<br><a href = index.html>[back to contents]</a> +<title>FLTK methods</title> + +<h2>#include <FL/Fl.H></h2> + +<p>You will have to include at least this header file in your main +code so that you can call the methods described here. + +<h2>Initialization</h2> + +<p><i>You can construct all your widgets (and menus and boxtypes and +images and other FLTK types) without "initializing".</i> The +constructors do not require a connection to the X display. This makes +it a lot easier, especially if your program has a mode where it does +not use a gui, and guarantees that code you don't use is not linked +in. + +<p>FLTK is usually "initialized" when you show() the first window. At +this time the X display is opened and everything is set up so the +calls described in the rest of this document work. A few other calls +can open the X display, amoung them are fl_width() to measure the +size of a font. Be careful that the following calls are done before +the display is opened, if not you will get lots of strange X errors. + +<p>Most of these "initialization" calls are to get around stupid X +things. I have tried to make these as simple to call as possible and +they have no effect on systems which aren't as badly designed as X. +But you should call them to make your program as portable as possible. + +<a name=visual> +</ul><h4><tt>int Fl::visual(int)</tt></h4><ul> + +Selects an X visual so that your graphics are drawn correctly. This +does nothing if the default visual satisfies the capabilities, or if +no visual satisfies the capabilities, or on systems that don't have +such brain-dead notions. + +<p>Only the following combinations do anything useful: + +<ul> + +<p><li><tt>Fl::visual(FL_RGB)</tt> + +<br>Full/true color (if there are several depths FLTK chooses the +largest). Do this if you use <a +href=images.html#fl_draw_image>fl_draw_image</a> for much better +(non-dithered) output. + +<p><li><tt>Fl::visual(FL_RGB8)</tt> + +<br>Full color with at least 24 bits of color. FL_RGB will always +pick this if available, but if not it will happily return a +less-than-24 bit deep visual. This call fails if 24 bits are not +available. + +<p><li><tt>Fl::visual(FL_DOUBLE|FL_INDEX)</tt> + +<br>Hardware double buffering. Call this if you are going to use +<a href=Fl_Double_Window.html>Fl_Double_Window</a>. + +<p><li><tt>Fl::visual(FL_DOUBLE|FL_RGB)</tt> +<li><tt>Fl::visual(FL_DOUBLE|FL_RGB8)</tt> + +<br>Hardware double buffering and full color. + +</ul> + +<p>This returns true if the system has the capabilities by default or +FLTK suceeded in turing them on. Your program will still work even if +this returns false (it just won't look as good). + +<p>See <a href=x.html#visuals>here</a> for ways to select the visual +using your own code. + +<a name=gl_visual> +</ul><h4><tt>int Fl::gl_visual(int)</tt></h4><ul> + +This does the same thing as Fl::visual(int) but also requires OpenGL +drawing to work. This <i>must</i> be done if you want to draw in +normal windows with OpenGL with <a href=Fl_Gl_Window.html#gl_start>gl_start() +and gl_end()</a>. It may be useful to call this so your X windows use +the same visual as an <a href=Fl_Gl_Window.html>Fl_Gl_Window</a>, on +some servers the windows will drag around easier then. + +<p>See <a href=Fl_Gl_Window.html#mode>Fl_Gl_Window</a> for a list of +additional values for the argument. + +</ul><h4><tt>void Fl::own_colormap();</tt></h4><ul> + +Makes FLTK use it's own X colormap. This may make FLTK display +better and will reduce conflicts with other programs that want lots of +colors. However the colors may flash as you drag the cursor between +windows. + +<p>This does nothing if the current visual is not colormapped or on +MSWindows (even though it probably should if your display is in 8-bit +mode). + +</ul><h4><tt>void Fl::get_system_colors();</tt></h4><ul> + +Read the user preference colors from the system and use them to call +Fl::foreground(), Fl::background(), and Fl::background2(). This is +done by Fl_Window::show(argc,argv) before applying the -fg and -bg +switches. + +<p>Currently this only works on MSWindows. In future versions on X it +may read the KDE or Gnome setup, but for now it does nothing. + +</ul><h4><tt>void Fl::background(uchar, uchar, uchar);</tt></h4><ul> + +Changes <tt>fl_color(FL_GRAY)</tt> to the given color, and changes +the gray ramp from 32 to 56 to black to white. These are the colors +used as backgrounds by almost all widgets and used to draw the edges +of all the boxtypes. + +</ul><h4><tt>void Fl::foreground(uchar, uchar, uchar);</tt></h4><ul> + +Changes <tt>fl_color(FL_BLACK)</tt>. Also changes +<tt>FL_INACTIVE_COLOR</tt> and <tt>FL_SELECTION_COLOR</tt> to +be a ramp between this and <tt>FL_WHITE</tt>. + +</ul><h4><tt>void Fl::background2(uchar, uchar, uchar);</tt></h4><ul> + +Changes <tt>fl_color(FL_WHITE)</tt> and the same colors as +Fl::foreground(). This color is used as a background by Fl_Input and +other text widgets. + +</ul><h4><tt>int Fl::args(int argc, char** argv, int +&i, int (*callback)(int,char**,int&)=0)</tt></h4><ul> + +<p>FLTK provides an <i>entirely optional</i> command-line switch +parser. You don't have to call it if you don't like them! +Everything it can do can be done with other calls to FLTK. + +<p>To use the switch parser, call Fl::args(...) near the start of +your program. This does <i>not</i> open the display, instead switches +that need the display open are stashed into static variables. Then +you <i>must</i> display your first window by calling <a +href=#show>Fl_Window::show(argc,argv)</a>, which will do anything +stored in the static variables. + +<p><i>callback</i> lets you define your own switches. It is called +with the same argc and argv, and with <i>i</i> the index of each word. +The callback should return zero if the switch is unrecognized, and not +change i. It should return non-zero if the switch is recognized, and +add at least 1 to i (it can add more to consume words after the +switch). This function is called before any other tests, so you can +override any FLTK switch. + +<p>On return <i>i</i> is set to the index of the first non-switch. +This is either: + +<p><ul> + +<li>The first word that does not start with '-'. + +<li>The word '-' (used by many programs to name stdin as a file) + +<li>The first word <i>after</i> '--' + +<li>The first unrecognized switch (return value is 0). + +<li>argc + +</ul> + +<p>The return value is <i>i</i> unless an unrecognized switch is +found, in which case it is zero. If your program takes no arguments +other than switches you should produce an error if the return value is +less than argc. + +<p>All switches may be abbreviated to one letter and case is ignored: + +<p><tt><b>-display host:n.n</b> </tt>The X display to use (ignored +by MSWindows). + +<p><tt><b>-geometry WxH+X+Y</b> </tt>The window position and size +will be modified according the the standard X geometry string. + +<p><tt><b>-name string</b> Fl_Window::xclass(string)</tt> will be +done to the window, this will change it's icon. + +<p><tt><b>-title string</b> Fl_Window::label(string)</tt> will be +done to the window, changing both it's title and the icontitle. + +<p><tt><b>-iconic</b> Fl_Window::iconize()</tt> will be done to +the window. + +<p><tt><b>-bg color</b> </tt>XParseColor is used to lookup the +passed color and then Fl::background() is done. On MSWindows +only color names of the form "#xxxxxx" are understood. + +<p><tt><b>-bg2 color</b> </tt>XParseColor is used to lookup the +passed color and then Fl::background2() is done. + +<p><tt><b>-fg color</b> </tt>XParseColor is used to lookup the +passed color and then Fl::foreground() is done. + +</ul><h4><tt>int Fl::arg(int argc, char** argv, int &i)</tt></h4><ul> + +Consume a single switch from argv, starting at word i. Returns the +number of words eaten (1 or 2, or 0 if it is not recognized) and adds +the same value to i. You can use this function if you prefer to +control the incrementing through the arguments yourself. + +</ul><h4><tt>void Fl::args(int argc, char** argv)</tt></h4><ul> + +This method is useful if your program does not have command line +switches of it's own. It parses all the switches, and if any are not +recognized it calls <tt>Fl::abort(Fl::help)</tt>. + +</ul><h4><tt>const char* const Fl::help;</tt></h4><ul> + +A string descibing the switches understood by Fl::arg(), useful for +printing as an error message. + +<a name=show> +</ul><h4><tt>int Fl_Window::show(int argc, char** argv)</tt></h4><ul> + +show() a window and set the <tt>XA_WM_COMMAND</tt> attribute to +the passed argc/argv. If this is the first time this has been called +since Fl::args() or Fl::arg(), the results of those switches are used +to set the xclass(), label(), and other attributes of this window. + +<p>If Fl::args() or Fl::arg() have never been called, this calls +Fl::args(argc,argv) automatically. This is convienent for very small +programs that just want to put up a single window and take no +switches. + +</ul> + +<h2>Running</h2> + +After FLTK is "initialized" by calling show() on some window, you get +FLTK to wait for and respond to events by calling the following +methods: + +<a name=run> +</ul><h4><tt>int Fl::run()</tt></h4><ul> + +Runs FLTK until there are no windows displayed, and then returns a zero. +Fl::run() is <i>exactly equivalent to:</i> + +<ul><tt><pre> +while (Fl::wait()); +return 0; +</pre></tt></ul> + +<A name=wait> +</ul><h4><tt>int Fl::wait()</tt></h4><ul> + +Calls the idle function if any, then calls any pending timeout +functions, then calls <a href=#flush>Fl::flush()</a>. If there are +any windows displayed it then waits some time for events (zero if +there is an idle(), the shortest timeout if there are any timeouts, or +forever) and calls the handle() function on those events, and then +returns non-zero. + +<p>Your program can check it's global state and update things after +each call to Fl::wait(), which can be very useful in complex programs. + +<p>If there are no windows (this is checked after the idle and +timeouts are called) then Fl::wait() returns zero without waiting for +any events. Your program can either exit at this point, or call +show() on some window so the UI can continue to operate. + +</ul><h4><tt>float Fl::wait(float time)</tt></h4><ul> + +Wait only a certain amount of time for anything to happen. This does +the same as wait() except if the given time (in seconds) passes it +returns. The return value is how much time remains. If the return +value is zero or negative then the entire time period elapsed. + +<p>If you do several wait(time) calls in a row, the subsequent ones +are measured from when the first one is called, even if you do +time-consuming calculations after they return. This allows you to +accurately make something happen at regular intervals. This code will +accurately call A() once per second (as long as it takes less than a +second to execute): + +<ul><tt><pre> +for (;;) { + for (float time = 1.0; time > 0; ) time = Fl::wait(time); + A(); +} +</pre></tt></ul> + +</ul><h4><tt>int Fl::check()</tt></h4><ul> + +This does the same thing as Fl::wait(0), except because it does not +have to return the elapsed time value it can be implemented faster on +certain systems. Use this to interrupt a big calculation: + +<ul><tt><pre> +while (!calculation_done()) { + calculate(); + Fl::check(); + if (user_hit_abort_button()) break; +} +</pre></tt></ul> + +<p>This returns non-zero if any windows are displayed, and 0 if no +windows are displayed. + +</ul><h4><tt>int Fl::ready();</tt></h4><ul> + +Returns non-zero if there are pending timeouts or X events or file +descriptors. This does <i>not</i> call Fl::flush() or any callbacks, +which is useful if your program is in a state where such callbacks are +illegal: + +<ul><tt><pre> +while (!calculation_done()) { + calculate(); + if (Fl::ready()) { + do_expensive_cleanup(); + Fl::check(); + if (user_hit_abort_button()) break; + } +} +<a name=add_timeout> +</pre></tt></ul> + +</ul><h4><tt>void Fl::add_timeout(float t,void (*cb)(void*),void* v=0); +<br>void Fl::remove_timeout(void (*cb)(void*), void* = 0);</tt></h4><ul> + +Add or remove a one-shot timeout callback. The timeout will happen as +soon as possible after <i>t</i> seconds after the last time wait() was +called. The optional void* argument is passed to the callback. It is +harmless to remove a timeout callback that no longer exists. + +<p>This code will print "TICK" each second on stdout, no matter what +else the user or program does: + +<ul><tt><pre> +void callback(void *) { + printf("TICK\n"); + Fl::add_timeout(1.0,callback); +} +main() {... + Fl::add_timeout(1.0,callback); + Fl::run(); +} +</pre></tt></ul> + +<a name=idle> +</ul><h4><tt>void Fl::set_idle(void (*cb)());</tt></h4><ul> + +If the idle callback is set it will be called by Fl::wait() and +Fl::wait() will return immediately. This can be used for background +processing. <i>This will absorb all your machine's time!</i> There is +only one idle callback, changing it will replace the old one. To turn +off the idle processing use Fl::set_idle(0). + +<p>Only Fl::wait(void) calls the idle callback. Fl::wait(time), +Fl::check(), and Fl::ready() ignore it. This is so that these +functions may be called by the idle callback itself without having to +worry about recursion. + +<p>The idle callback can call any FLTK functions. However if you call +something that calls Fl::wait() (such as a message pop-up) you should +first set the idle callback to zero so it does not recurse. + +<a name=flush> +</ul><h4><tt>void Fl::flush()</tt></h4><ul> + +Causes all the windows that need it to be redrawn and graphics forced +out through the pipes. This is what wait() does before looking for +events. + +</ul><h4><tt>int Fl::damage()</tt></h4><ul> + +If true then <a href=#flush>flush()</a> will do something. + +<a name=readqueue> +</ul><h4><tt>Fl_Widget *Fl::readqueue();</tt></h4><ul> + +All Fl_Widgets that don't have a callback defined use a default callback +that puts a pointer to the widget in this queue, and this method reads +the oldest widget out of this queue. + +<a name=add_fd> +</ul> +<h2>Listening to other file descriptors (Unix only)</h2> + +<h4><tt> +void Fl::add_fd(int fd, void (*cb)(int, void*), void* = 0);<br> +void Fl::add_fd(int fd, int when, void (*cb)(int, void*), void* = 0);<br> +void Fl::remove_fd(int);</tt></h4><ul> + +Add file descriptor <i>fd</i> to listen to. When the fd becomes ready +for reading the callback is done. The callback is passed the fd and +the arbitrary void* argument. Fl::wait() will return immediately +after calling the callback. + +<p>The second version takes a <i>when</i> bitfield, with the bits +FL_READ, FL_WRITE, and FL_EXCEPT defined, to indicate when the +callback should be done. This probably only works on Unix. + +<p>There can only be one callback of each type for a file descriptor. +Fl::remove_fd() gets rid of <i>all</i> the callbacks for a given file +descriptor. + +</ul> + +<h2>Exiting</h2> + +When all windows are closed Fl::wait() and Fl::run() return zero. If +your main() routine then returns the program exits. You can also call +exit(0) at any time in your program. <i>You do not need to do any +cleanup code for FLTK.</i> In particular you do not have to destroy +any widgets you have created. FLTK also does not sneak any atexit +functions in on you either. You will need to do<tt> +#include <stdlib.h> </tt>to call exit(). + +<p>To stop a window from closing, or conversely to make the closing of +a particular window exit the program you must change the callback() +function. Here is a typical use: + +<ul><tt><pre> +static void main_window_cb(Fl_Widget*, void*) { + if (document_changed()) { + if (!fl_ask("Exit without saving changes?")) return; + // window will not go away as hide() has not been called... + } + exit(0); +} + +...somewhere in main(): + main_window->callback(window_cb); +</pre></tt></ul> + +<a name=fatal> +</ul><h4><tt>void (*Fl::warning)(const char*,...); +<br>void (*Fl::error)(const char*,...); +<br>void (*Fl::fatal)(const char*,...);</tt></h4><ul> + +FLTK will call these to print messages when unexpected conditions +occur. By default they fprintf to stderr, and Fl::error and Fl::fatal +call exit(1). You can override the behavior by setting the function +pointers to your own routines. + +<p>Supposedly Fl::warning means that there was a recoverable problem, +the display may be messed up but the user can probably keep working +(all X protocol errors call this). Fl::error means there is a +recoverable error, but the display is so messed up it is unlikely the +user can continue (very little calls this now). Fl::fatal must not +return, as FLTK is in an unusable state (however your version may be +able to use longjmp or an exception to continue, as long as it does +not call FLTK again). + +</ul><p><a href = index.html>(back to contents)</a> +<title>FLTK example: hello.C</title> +<h2>hello.C</h2> + + +<p><a href = button.C.html>[Next example]</a> +<br><a href = index.html>[back to contents]</a> + +</BODY> +</HTML> diff --git a/documentation/glut.html b/documentation/glut.html new file mode 100644 index 000000000..3cbfdb50e --- /dev/null +++ b/documentation/glut.html @@ -0,0 +1,145 @@ +<HTML> +<BODY> + +<H1 ALIGN=RIGHT><A NAME="glut">D - GLUT Compatibility</A></H1> + +You should be able to compile existing Glut source code by +including <FL/glut.H> instead of <GL/glut.h>. This can be done by +editing the source, by changing the -I switches to the compiler, or by +providing a symbolic link from GL/glut.h to FL/glut.H. + +<p>All files calling glut procedures must be compiled with C++. You may +have to alter them slightly to get them to compile without warnings, +and you may have to rename them to get make to use the C++ compiler. +I was unable to get some calls to glu to compile without adding some +casts, apparently due to errors in the glu header files. + +<p>You must link with -lFl. If you call any glut drawing functions +that fltk does not emulate (<code>glutExtensionsSupported(), glutWire*(), +glutSolid*(), and glutStroke*()</code>), you will also have to link with +-lglut, <i>after</i> -lFl. + +<p>Most of glut.H is inline functions. You should take a look at it +(and maybe at glut.C in the fltk source) if you are having trouble +porting your Glut program. + +<p>This has been tested with most of the demo programs that come with +the Glut 3.3 distribution. + +<h2>Known Problems</h2> + +<ul> + +<li>The following functions and/or arguments to functions are missing, +and you will have to replace them or comment them out for your code to +compile:<ul> + +<li><code>glutLayerGet(GLUT_LAYER_IN_USE)</code> +<li><code>glutLayerGet(GLUT_HAS_OVERLAY)</code> +<li><code>glutSetColor(), glutGetColor(), glutCopyColormap()</code> +<li><code>glutInitDisplayMode(GLUT_STEREO)</code> +<li><code>glutInitDisplayMode(GLUT_LUMINANCE)</code> +<li><code>glutPushWindow()</code> +<li><code>glutWarpPointer()</code> +<li>Spaceball, buttonbox, dials, tablet functions, <code>glutDeviceGet()</code> +<li><code>glutWindowStatusFunc()</code> +<li><code>glutGet(GLUT_WINDOW_NUM_CHILDREN)</code> +<li><code>glutGet(GLUT_SCREEN_WIDTH_MM)</code> +<li><code>glutGet(GLUT_SCREEN_HEIGHT_MM)</code> +<li><code>glutGet(GLUT_ELAPSED_TIME)</code> +<li><code>glutVideoResize()</code> missing. + +</ul> + +<li>Most of the symbols/enumerations have different values than +Glut uses. This will break code that relies on the actual values. +The only symbols guaranteed to have the same values are true/false +pairs like <code>GLUT_DOWN</code> and <code>GLUT_UP</code>, mouse +buttons <code>GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON, +GLUT_RIGHT_BUTTON</code>, and <code>GLUT_KEY_F1</code> thru +<code>F12</code>. + +<li><i>The strings passed as menu labels are not copied</i>. + +<li><code>glutPostRedisplay()</code> does not work if called from +inside a display function. You must use <code>glutIdleFunc()</code> +if you want your display to update continuously. + +<li><code>glutSwapBuffers()</code> does not work from inside a display +function. This is on purpose, because fltk swaps the buffers for you. + +<li><code>glutUseLayer()</code> does not work well, and should only be +used to initialize transformations inside a resize callback. You +should redraw overlays by using <code>glutOverlayDisplayFunc()</code>. + +<li>Overlays are cleared before the overlay display function is +called. <code>glutLayerGet(GLUT_OVERLAY_DAMAGED)</code> always +returns true, this fixed some glut overlay programs. You must rewrite +your code so that gl_color() is used to choose colors in an overlay, +or you will get random overlay colors. + +<li><code>glutSetCursor(GLUT_CURSOR_FULL_CROSSHAIR)</code> just +results in a small crosshair. + +<li>The fonts used by <code>glutBitmapCharacter() and +glutBitmapWidth()</code> may be different. + +<li><code>glutInit(argc,argv)</code> will consume different switches than glut +does. It accepts the switches recognized by <a +href=Fl.html>Fl_Window::arg()</a>, and will accept any +abbreviation of these switches (such as -d for -display). + +</ul> + +<h2>Mixing Glut code and Fltk code</h2> + +You can make your Glut window a child of a Fl_Window with the +following scheme. The biggest trick is that Glut insists on +show()'ing the window at the point it is created, which means the +Fl_Window parent window must already be show()n. + +<p>Don't call glutInit(). + +<p>Create your Fl_Window, and any fltk widgets. Leave a blank area in +the window for your glut window. + +<p>show() the Fl_Window. Perhaps call show(argc,argv). + +<p>Call window->begin() so the glut window will be automatically added +to it. + +<p>Use glutInitWindowSize() and glutInitWindowPosition() to set the +location in the parent window to put the glut window. + +<p>Put your glut code next. It probably does not need many changes. +Call window->end() immediately after the glutCreateWindow()! + +<p>You can call either glutMainLoop() or Fl::run() or loop calling +Fl::wait() to run the program. + +<h2>class Fl_Glut_Window : public <a href=Fl_Gl_Window.html>Fl_Gl_Window</a></h2> + +Each Glut window is an instance of this class, which is a subclass of +<a href=Fl_Gl_Window.html>Fl_Gl_Window</a>. You may find it useful to +manipulate instances directly rather than use glut window id's. These +may be created without opening the display, and thus can fit better +into FL's method of creating windows. + +<p>The current glut window is available in <code>Fl_Glut_Window +*glut_window</code>. + +<p><code>new Fl_Glut_Window(...)</code> is the same as +<code>glutCreateWindow()</code> except it does not show() the window +or make the window current. + +<p><code>window->make_current()</code> is the same as +<code>glutSetWindow(number)</code>. If the window has not had show() +called on it yet, some functions that assumme a gl context will not +work. If you do show() the window, call make_current() again to set +the context. + +<p><code>~Fl_Glut_Window()</code> is the same as +<code>glutDestroyWindow()</code>. + +</BODY> +</HTML> diff --git a/documentation/hello.C.gif b/documentation/hello.C.gif Binary files differnew file mode 100644 index 000000000..c051dffc8 --- /dev/null +++ b/documentation/hello.C.gif diff --git a/documentation/intro.html b/documentation/intro.html new file mode 100644 index 000000000..39b73c225 --- /dev/null +++ b/documentation/intro.html @@ -0,0 +1,260 @@ +<HTML> +<BODY> + +<H1 ALIGN=RIGHT><A NAME="intro">1 - Introduction to FLTK</A></H1> + +The Fast Light Tool Kit ("FLTK", pronounced "fulltick") is a LGPL'd C++ +graphical user interface toolkit for X (UNIX®), OpenGL®, and +Microsoft® Windows® NT 4.0, 95, or 98. It is currently +maintained by a small group of developers across the world with a +central repository in the US. + +<h2>History of FLTK</h2> + +It has always been Bill's belief that the GUI API of all modern systems +is much too high level. Toolkits (even FL) are <i>not</i> what should +be provided and documented as part of an operating system. The system +only has to provide arbitrary shaped but featureless windows, a +powerful set of graphics drawing calls, and a simple <i>unalterable</i> +method of delivering events to the owners of the windows. NeXT (if you +ignored NextStep) provided this, but they chose to hide it and tried to +push their own baroque toolkit instead... + +<p>Many of the ideas in FLTK were developed on a NeXT (but <i>not</i> +using NextStep) in 1987 in a C toolkit Bill called "views". Here he +came up with passing events downward in the tree and having the handle +routine return a value indicating the used the event, and the +table-driven menus. In general he was trying to prove that complex UI +ideas could be entirely implemented in a user space toolkit, with no +knowledge or support by the system. + +<p>After going to film school for a few years, Bill worked at Sun +Microsystems on the (doomed) NeWS project. Here he found an even +better and cleaner windowing system, and he reimplemented "views" atop +that. NeWS did have an unnecessarily complex method of delivering +events which hurt it. But the designers did admit that perhaps the +user could write just as good of a button as they could, and officially +exposed the lower level interface. + +<p>With the death of NeWS Bill realized that he would have to live with +X. The biggest problem with X is the "window manager", which means +that the toolkit can no longer control the window borders or drag the +window around. + +<p>At Digital Domain Bill discovered another toolkit, "Forms". Forms was +similar to his work, but provided many more widgets, since it was used +in many real applications, rather then as theoretical work. He decided +to use Forms, except he integrated my table-driven menus into it. +Several very large programs were created using this version of Forms. + +<p>The need to switch to OpenGL and GLX, portability, and a desire to +use C++ subclassing required a rewrite of Forms. This produced the +first version of FLTK. The conversion to C++ required so many changes +it made it impossible to recompile any Forms objects. Since it was +incompatable anyway, Bill decided to incorporate as much as possible my +older ideas on simplifying the lower level interface and the event +passing mechanisim. + +<p>Bill received permission to release it for free on the Internet, +with the GNU general public license. Response from Internet users +indicated that the Linux market dwarfed the SGI and high-speed GL +market, so he rewrote it to use X for all drawing, greatly speeding it +up on these machines. That is the version you have now. + +<p>Digital Domain has since withdrawn support for FLTK. While Bill is +no longer able to actively develop it, he still contributes to FLTK in +his free time and is a part of the FLTK development team. + +<h2>Features</h2> + +FLTK was designed to be statically linked. This was done by splitting it +into many small objects and desigining it so that functions that are not +used do not have pointers to them in the parts that are used, and thus +do not get linked in. This allows you to make an easy-to-install program, +or to modify FLTK to the exact requirements of your application, without +worrying about bloat. FLTK works fine as a shared library, though, and +has started being included on Linux distributions. + +<p>Here are some of the core features unique to FLTK: + +<ul> + <li>sizeof(Fl_Widget) == 48.</li> + + <li>The "core" (the "hello" program compiled & linked with a static FLTK + library using gcc on a 486 and then stripped) is 39.5K.</li> + + <li>A program including every widget is less than 108K. Does not use + macros, templates, multiple inheritance, or exceptions.</li> + + <li>Written directly atop Xlib (or WIN32) for maximum speed, + and carefully optimized for code size and performance.</li> + + <li>Precise low-level compatability between the X11 and WIN32 + version (only about 10% of the code is different).</li> + + <li>Interactive user interface builder program. Output is + human-readable and editable C++ source code.</li> + + <li>Support for the X11 double buffering extension (emulation + if not available and under Windows.)</li> + + <li>Support for X11 overlay hardware (emulation if none and + under WIN32.)</li> + + <li>Very small & fast portable 2-D drawing library to hide + Xlib and WIN32.</li> + + <li>OpenGL/Mesa drawing area widget.</li> + + <li>Support for OpenGL overlay hardware on both X11 and WIN32. + Emulation if none.</li> + + <li>Text input fields with Emacs key bindings, X cut & + paste, and foreign letter compose!</li> + + <li>Compatability header file for the GLUT library.</li> + + <li>Compatability header file for the XForms library.</li> + + <li>Much too much to list here...</li> +</ul> + +<h2>Licensing</h2> + +FLTK comes with complete free source code. FLTK is available under the +terms of the <a href="#licensing">GNU Library General Public +License</a>. Contrary to popular belief, it can be used in commercial +software! (Even Bill Gates could use it.) + +<h2>What Does "FLTK" Mean?</h2> + +FLTK was originally designed to be compatable with the Forms Library written +for SGI machines. In that library all the functions and structures started +with "fl_". This naming was extended to all new methods and widgets in +the C++ library, and this prefix was taken as the name of the library. +It is almost impossible to search for "FL" on the Internet, due to the +fact that it is also the abbreviation for Florida. After much debating +and searching for a new name for the toolkit, which was already in use +by several people, Bill came up with "FLTK", and even a bogus excuse that +it stands for "The Fast Light Tool Kit". + +<h2>Building and Installing FLTK Under UNIX</h2> + +In most cases you can just type "make". This will run configure with +the default of no options and then compile everything. + +<p>FLTK uses GNU autoconf to configure itself for your UNIX platform. The +main things that the configure script will look for are the X11, OpenGL +(or Mesa), and JPEG header and library files. Make sure that they +are in the standard include/library locations. + +<p>You can run configure yourself to get the exact setup you need. Type +"./configure <options>", where options are: + +<dl> +<dt>--enable-debug</dt> + +<dd>Enable debugging code & symbols</dd> + +<dt>--enable-shared</dt> + +<dd>Enable generation of shared libraries</dd> + +<dt>--bindir=/path</dt> + +<dd>Set the location for executables [default = /usr/local/bin]</dd> + +<dt>--libdir=/path</dt> + +<dd>Set the location for libraries [default = /usr/local/lib]</dd> + +<dt>--includedir=/path</dt> + +<dd>Set the location for include files. [default = /usr/local/include]</dd> + +<dt>--prefix=/dir</dt> + +<dd>Set the directory prefix for files [default = /usr/local]</dd> +</dl> + +When the configure script is done you can just run the "make" command. +This will build the library, FLUID tool, and all of the test programs. + +<p>To install the library, become root and type "make install". This +will copy the "fluid" executable to "bindir", the header files to "includedir", +and the library files to "libdir". + +<h2>Building FLTK Under Micrsoft Windows</h2> + +There are two ways to build FLTK under Microsoft Windows. The first +is to use the Visual C++ 5.0 project files under the "visualc" directory. +Just open (or double-click on) the "fltk.dsw" file to get the whole shebang. + +<p>The second method is to use a GNU-based development tool with the files +in the "makefiles" directory. To build using one of these tools simply +copy the appropriate makeinclude and config files to the main directory +and do a make: + +<ul><pre> +cp makefiles/makeinclude.<env> makeinclude +cp makefiles/config.<env> config.h +make +</pre></ul> + +<h2>Building FLTK Under OS/2</h2> + +The current OS/2 build requires XFree86 for OS/2 to work. A native +Presentation Manager version has not been implemented yet (volunteers are +welcome!). + +<p>To build the XFree86 version of FLTK for OS/2, copy the appropriate +makeinclude and config files to the main directory and do a make: + +<ul><pre> +cp makefiles/Makefile.os2x Makefile +cp makefiles/makeinclude.os2x makeinclude +cp makefiles/config.os2x config.h +make +</pre></ul> + +<h2>Internet Resources</h2> + +FLTK is available on the 'net in a bunch of locations: + +<dl> +<dt>WWW</dt> + +<dd><a href="http://fltk.easysw.com">http://fltk.easysw.com</a></dd> + +<dt>FTP</dt> + +<dd><a href="ftp://ftp.easysw.com/pub/fltk">ftp://ftp.easysw.com/pub/fltk</a><br> +<a href="ftp://ftp.funet.fi/mirrors/ftp.easysw.com/pub/fltk">ftp://ftp.funet.fi/mirrors/ftp.easysw.com/pub/fltk</a><br> +<a href="ftp://ftp.northamerica.net/pub/ESP/fltk">ftp.northamerica.net/pub/ESP/fltk</a><br></dd> + +<dt>EMail</dt> + +<dd><a href="mailto:fltk@easysw.com">fltk@easysw.com</a> [see instructions below]</dd> + +<dd><a href="mailto:fltk-bugs@easysw.com">fltk-bugs@easysw.com</a> [for reporting bugs]</dd> +</dl> + +To send a message to the FLTK mailing list ("fltk@easysw.com") you must +first join the list. Non-member submissions are blocked to avoid +problems with SPAM... + +<p>To join the FLTK mailing list, send a message to "majordomo@easysw.com" +with "subscribe fltk" in the message body. A digest of this list is available +by subscribing to the "fltk-digest" mailing list. + +<h2>Reporting Bugs</h2> + +To report a bug in FLTK, send an email to "fltk-bugs@easysw.com". Please +include the FLTK version, operating system & version, and compiler +that you are using when describing the bug or problem. + +<p>For general support and questions, please use the FLTK mailing list +at "fltk@easysw.com". + +</body> +</html> diff --git a/documentation/license.html b/documentation/license.html new file mode 100644 index 000000000..2dbaaa5e0 --- /dev/null +++ b/documentation/license.html @@ -0,0 +1,468 @@ +<HTML> +<BODY> + +<H1 ALIGN=RIGHT><A NAME="license">G - Software License</A></H1> + +<H2>GNU LIBRARY GENERAL PUBLIC LICENSE</H2> + +<P>Version 2, June 1991<BR> +Copyright (C) 1991 Free Software Foundation, Inc.<BR> +59 Temple Place - Suite 330, Boston, MA 02111-1307, USA<BR> +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed.<BR> +[This is the first released version of the library GPL. It is +numbered 2 because it goes with version 2 of the ordinary GPL.] + +<H2>Preamble</H2> + +The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +Licenses are intended to guarantee your freedom to share and change +free software--to make sure the software is free for all its users. + +<P>This license, the Library General Public License, applies to some +specially designated Free Software Foundation software, and to any +other libraries whose authors decide to use it. You can use it for +your libraries, too. + +<P>When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + +<P>To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if +you distribute copies of the library, or if you modify it. + +<P>For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link a program with the library, you must provide +complete object files to the recipients so that they can relink them +with the library, after making changes to the library and recompiling +it. And you must show them these terms so they know their rights. + +<P>Our method of protecting your rights has two steps: (1) copyright +the library, and (2) offer you this license which gives you legal +permission to copy, distribute and/or modify the library. + +<P>Also, for each distributor's protection, we want to make certain +that everyone understands that there is no warranty for this free +library. If the library is modified by someone else and passed on, we +want its recipients to know that what they have is not the original +version, so that any problems introduced by others will not reflect on +the original authors' reputations. + +<P>Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that companies distributing free +software will individually obtain patent licenses, thus in effect +transforming the program into proprietary software. To prevent this, +we have made it clear that any patent must be licensed for everyone's +free use or not licensed at all. + +<P>Most GNU software, including some libraries, is covered by the ordinary +GNU General Public License, which was designed for utility programs. This +license, the GNU Library General Public License, applies to certain +designated libraries. This license is quite different from the ordinary +one; be sure to read it in full, and don't assume that anything in it is +the same as in the ordinary license. + +<P>The reason we have a separate public license for some libraries is that +they blur the distinction we usually make between modifying or adding to a +program and simply using it. Linking a program with a library, without +changing the library, is in some sense simply using the library, and is +analogous to running a utility program or application program. However, in +a textual and legal sense, the linked executable is a combined work, a +derivative of the original library, and the ordinary General Public License +treats it as such. + +<P>Because of this blurred distinction, using the ordinary General +Public License for libraries did not effectively promote software +sharing, because most developers did not use the libraries. We +concluded that weaker conditions might promote sharing better. + +<P>However, unrestricted linking of non-free programs would deprive the +users of those programs of all benefit from the free status of the +libraries themselves. This Library General Public License is intended to +permit developers of non-free programs to use free libraries, while +preserving your freedom as a user of such programs to change the free +libraries that are incorporated in them. (We have not seen how to achieve +this as regards changes in header files, but we have achieved it as regards +changes in the actual functions of the Library.) The hope is that this +will lead to faster development of free libraries. + +<P>The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +"work based on the libary" and a "work that uses the library". The +former contains code derived from the library, while the latter only +works together with the library. + +<P>Note that it is possible for a library to be covered by the ordinary +General Public License rather than by this special one. + +<H2>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</H2> + +<STRONG>0.</STRONG> This License Agreement applies to any software library which +contains a notice placed by the copyright holder or other authorized +party saying it may be distributed under the terms of this Library +General Public License (also called "this License"). Each licensee is +addressed as "you". + +<P>A "library" means a collection of software functions and/or data +prepared so as to be conveniently linked with application programs +(which use some of those functions and data) to form executables. + +<P>The "Library", below, refers to any such software library or work +which has been distributed under these terms. A "work based on the +Library" means either the Library or any derivative work under +copyright law: that is to say, a work containing the Library or a +portion of it, either verbatim or with modifications and/or translated +straightforwardly into another language. (Hereinafter, translation is +included without limitation in the term "modification".) + +<P>"Source code" for a work means the preferred form of the work for +making modifications to it. For a library, complete source code means +all the source code for all modules it contains, plus any associated +interface definition files, plus the scripts used to control compilation +and installation of the library. + +<P>Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running a program using the Library is not restricted, and output from +such a program is covered only if its contents constitute a work based +on the Library (independent of the use of the Library in a tool for +writing it). Whether that is true depends on what the Library does +and what the program that uses the Library does. + +<P><STRONG>1.</STRONG> You may copy and distribute verbatim copies of the Library's +complete source code as you receive it, in any medium, provided that +you conspicuously and appropriately publish on each copy an +appropriate copyright notice and disclaimer of warranty; keep intact +all the notices that refer to this License and to the absence of any +warranty; and distribute a copy of this License along with the +Library. + +<P>You may charge a fee for the physical act of transferring a copy, +and you may at your option offer warranty protection in exchange for a +fee. + +<P><STRONG>2.</STRONG> You may modify your copy or copies of the Library or any portion +of it, thus forming a work based on the Library, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +<BLOCKQUOTE> + +<STRONG>a)</STRONG> The modified work must itself be a software library. + +<P><STRONG>b)</STRONG> You must cause the files modified to carry prominent notices +stating that you changed the files and the date of any change. + +<P><STRONG>c)</STRONG> You must cause the whole of the work to be licensed at no +charge to all third parties under the terms of this License. + +<P><STRONG>d)</STRONG> If a facility in the modified Library refers to a function or a +table of data to be supplied by an application program that uses +the facility, other than as an argument passed when the facility +is invoked, then you must make a good faith effort to ensure that, +in the event an application does not supply such function or +table, the facility still operates, and performs whatever part of +its purpose remains meaningful. + +<P>(For example, a function in a library to compute square roots has +a purpose that is entirely well-defined independent of the +application. Therefore, Subsection 2d requires that any +application-supplied function or table used by this function must +be optional: if the application does not supply it, the square +root function must still compute square roots.) + +</BLOCKQUOTE> + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Library, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Library, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote +it. + +<P>Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Library. + +<P>In addition, mere aggregation of another work not based on the Library +with the Library (or with a work based on the Library) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +<P><STRONG>3.</STRONG> You may opt to apply the terms of the ordinary GNU General Public +License instead of this License to a given copy of the Library. To do +this, you must alter all the notices that refer to this License, so +that they refer to the ordinary GNU General Public License, version 2, +instead of to this License. (If a newer version than version 2 of the +ordinary GNU General Public License has appeared, then you can specify +that version instead if you wish.) Do not make any other change in +these notices. + +<P>Once this change is made in a given copy, it is irreversible for +that copy, so the ordinary GNU General Public License applies to all +subsequent copies and derivative works made from that copy. + +<P>This option is useful when you wish to copy part of the code of +the Library into a program that is not a library. + +<P><STRONG>4.</STRONG> You may copy and distribute the Library (or a portion or +derivative of it, under Section 2) in object code or executable form +under the terms of Sections 1 and 2 above provided that you accompany +it with the complete corresponding machine-readable source code, which +must be distributed under the terms of Sections 1 and 2 above on a +medium customarily used for software interchange. + +<P>If distribution of object code is made by offering access to copy +from a designated place, then offering equivalent access to copy the +source code from the same place satisfies the requirement to +distribute the source code, even though third parties are not +compelled to copy the source along with the object code. + +<P><STRONG>5.</STRONG> A program that contains no derivative of any portion of the +Library, but is designed to work with the Library by being compiled or +linked with it, is called a "work that uses the Library". Such a +work, in isolation, is not a derivative work of the Library, and +therefore falls outside the scope of this License. + +<P>However, linking a "work that uses the Library" with the Library +creates an executable that is a derivative of the Library (because it +contains portions of the Library), rather than a "work that uses the +library". The executable is therefore covered by this License. +Section 6 states terms for distribution of such executables. + +<P>When a "work that uses the Library" uses material from a header file +that is part of the Library, the object code for the work may be a +derivative work of the Library even though the source code is not. +Whether this is true is especially significant if the work can be +linked without the Library, or if the work is itself a library. The +threshold for this to be true is not precisely defined by law. + +<P>If such an object file uses only numerical parameters, data +structure layouts and accessors, and small macros and small inline +functions (ten lines or less in length), then the use of the object +file is unrestricted, regardless of whether it is legally a derivative +work. (Executables containing this object code plus portions of the +Library will still fall under Section 6.) + +<P>Otherwise, if the work is a derivative of the Library, you may +distribute the object code for the work under the terms of Section 6. +Any executables containing that work also fall under Section 6, +whether or not they are linked directly with the Library itself. + +<P><STRONG>6.</STRONG> As an exception to the Sections above, you may also compile or +link a "work that uses the Library" with the Library to produce a +work containing portions of the Library, and distribute that work +under terms of your choice, provided that the terms permit +modification of the work for the customer's own use and reverse +engineering for debugging such modifications. + +<P>You must give prominent notice with each copy of the work that the +Library is used in it and that the Library and its use are covered by +this License. You must supply a copy of this License. If the work +during execution displays copyright notices, you must include the +copyright notice for the Library among them, as well as a reference +directing the user to the copy of this License. Also, you must do one +of these things: + +<BLOCKQUOTE> + +<STRONG>a)</STRONG> Accompany the work with the complete corresponding + machine-readable source code for the Library including whatever + changes were used in the work (which must be distributed under + Sections 1 and 2 above); and, if the work is an executable linked + with the Library, with the complete machine-readable "work that + uses the Library", as object code and/or source code, so that the + user can modify the Library and then relink to produce a modified + executable containing the modified Library. (It is understood + that the user who changes the contents of definitions files in the + Library will not necessarily be able to recompile the application + to use the modified definitions.) + +<P><STRONG>b)</STRONG> + Accompany the work with a written offer, valid for at + least three years, to give the same user the materials + specified in Subsection 6a, above, for a charge no more + than the cost of performing this distribution. + +<P><STRONG>c)</STRONG> + If distribution of the work is made by offering access to copy + from a designated place, offer equivalent access to copy the above + specified materials from the same place. + +<P><STRONG>d)</STRONG> + Verify that the user has already received a copy of these + materials or that you have already sent this user a copy. +</BLOCKQUOTE> + +For an executable, the required form of the "work that uses the +Library" must include any data and utility programs needed for +reproducing the executable from it. However, as a special exception, +the source code distributed need not include anything that is normally +distributed (in either source or binary form) with the major +components (compiler, kernel, and so on) of the operating system on +which the executable runs, unless that component itself accompanies +the executable. + +<P>It may happen that this requirement contradicts the license +restrictions of other proprietary libraries that do not normally +accompany the operating system. Such a contradiction means you cannot +use both them and the Library together in an executable that you +distribute. + +<P><STRONG>7.</STRONG> + You may place library facilities that are a work based on the +Library side-by-side in a single library together with other library +facilities not covered by this License, and distribute such a combined +library, provided that the separate distribution of the work based on +the Library and of the other library facilities is otherwise +permitted, and provided that you do these two things: + +<BLOCKQUOTE> + +<STRONG>a)</STRONG> + Accompany the combined library with a copy of the same work + based on the Library, uncombined with any other library + facilities. This must be distributed under the terms of the + Sections above. + +<P><STRONG>b)</STRONG> + Give prominent notice with the combined library of the fact + that part of it is a work based on the Library, and explaining + where to find the accompanying uncombined form of the same work. +</BLOCKQUOTE> + +<STRONG>8.</STRONG> + You may not copy, modify, sublicense, link with, or distribute +the Library except as expressly provided under this License. Any +attempt otherwise to copy, modify, sublicense, link with, or +distribute the Library is void, and will automatically terminate your +rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses +terminated so long as such parties remain in full compliance. + +<P><STRONG>9.</STRONG> + You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Library or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Library (or any work based on the +Library), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Library or works based on it. + +<P><STRONG>10.</STRONG> + Each time you redistribute the Library (or any work based on the +Library), the recipient automatically receives a license from the +original licensor to copy, distribute, link with or modify the Library +subject to these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +<P><STRONG>11.</STRONG> + If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Library at all. For example, if a patent +license would not permit royalty-free redistribution of the Library by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Library. + +<P>If any portion of this section is held invalid or unenforceable under any +particular circumstance, the balance of the section is intended to apply, +and the section as a whole is intended to apply in other circumstances. + +<P>It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +<P>This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +<P><STRONG>12.</STRONG> + If the distribution and/or use of the Library is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Library under this License may add +an explicit geographical distribution limitation excluding those countries, +so that distribution is permitted only in or among countries not thus +excluded. In such case, this License incorporates the limitation as if +written in the body of this License. + +<P><STRONG>13.</STRONG> + The Free Software Foundation may publish revised and/or new +versions of the Library General Public License from time to time. +Such new versions will be similar in spirit to the present version, +but may differ in detail to address new problems or concerns. + +<P>Each version is given a distinguishing version number. If the Library +specifies a version number of this License which applies to it and +"any later version", you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Library does not specify a +license version number, you may choose any version ever published by +the Free Software Foundation. + +<P><STRONG>14.</STRONG> + If you wish to incorporate parts of the Library into other free +programs whose distribution conditions are incompatible with these, +write to the author to ask for permission. For software which is +copyrighted by the Free Software Foundation, write to the Free +Software Foundation; we sometimes make exceptions for this. Our +decision will be guided by the two goals of preserving the free status +of all derivatives of our free software and of promoting the sharing +and reuse of software generally. + +<H2>NO WARRANTY</H2> + +<P><STRONG>15.</STRONG> + BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE +LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +<P><STRONG>16.</STRONG> + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A +FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF +SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES. + +<H2>END OF TERMS AND CONDITIONS</H2> + +</BODY> +</HTML> diff --git a/documentation/menu.gif b/documentation/menu.gif Binary files differnew file mode 100644 index 000000000..6ed0f6d32 --- /dev/null +++ b/documentation/menu.gif diff --git a/documentation/menu_button.gif b/documentation/menu_button.gif Binary files differnew file mode 100644 index 000000000..5ee9b58ec --- /dev/null +++ b/documentation/menu_button.gif diff --git a/documentation/menubar.gif b/documentation/menubar.gif Binary files differnew file mode 100644 index 000000000..955b81a35 --- /dev/null +++ b/documentation/menubar.gif diff --git a/documentation/opengl.html b/documentation/opengl.html new file mode 100644 index 000000000..e26895a2c --- /dev/null +++ b/documentation/opengl.html @@ -0,0 +1,486 @@ +<HTML> +<BODY> + +<H1 ALIGN=RIGHT><A NAME="opengl">7 - Using OpenGL</A></H1> + +This chapter discusses using FLTK for your OpenGL applications. + +<H2>The OpenGL Widget</H2> + +<H2>Making a Simple OpenGL Wrapper Widget</H2> + +<H2>A Simple Flight Simulator</H2> + +<H2>Using FLTK with OpenGL Optimizer</H2> + +<H2>Using OpenGL Optimizer for the Flight Simulator</H2> + +</BODY> +</HTML> +<title>Using OpenGL in Fltk</title> + +<h2>Using OpenGL in Fltk<br>#include <FL/gl.h></h2> + +The easiest way to make an OpenGL display is to subclass Fl_Gl_Window. +Your subclass should implement a draw() method which uses OpenGL calls +to draw the display. Your main program should call w->redraw() when +the display needs to change, and (somewhat later) fltk will call +draw(). + +<p>With a bit of care you can also use OpenGL to draw into normal fltk +windows. This is mostly useful because you can access Gourand shading +for drawing your widgets. To do this you use the <a +href=#gl_start>gl_start() and gl_finish()</a> functions around your +OpenGL code. + +<p>You must include fltk's <FL/gl.h> header file. It will include +the file <GL/gl.h>, plus it defines some extra drawing functions +provided by fltk, and also gets around a horrid screwup by our friends +in Seattle. + +<h2>Sample code for subclassing Fl_Gl_Window</h2> + +<p><pre> + class MyWindow : public Fl_Gl_Window { + void draw(); + int handle(int); + public: + MyWindow(int X, int Y, int W, int H, const char* L) + : Fl_Gl_Window(X,Y,W,H,L) {} + }; + + void MyWindow::draw() { + if (!valid()) { + ... set up projection, viewport, etc ... + ... window size is in w() and h(). + ... valid() is turned on by fltk after draw() returns + } + ... draw ... + } + + int MyWindow::handle(int event) { + switch(event) { + case FL_PUSH: + ... mouse down event ... + ... position in Fl::event_x() and Fl::event_y() + return 1; + case FL_DRAG: + ... mouse moved while down event ... + return 1; + case FL_RELEASE: + ... mouse up event ... + return 1; + case FL_KEYBOARD: + ... keypress, key is in Fl::event_key(), ascii in Fl::event_text() + return 1; + default: + // tell fltk that I don't understand other events + return 0; + } + } +</pre> + +<p>When handle() is called, the glx context is not set up! If your +display changes, you should call redraw() and let draw() do the work. +Don't call any gl functions from inside handle()! + +<p>This may mean you cannot call some OpenGl stuff like hit detection. +You can fix this by doing: + +<p><pre> + case FL_PUSH: + make_current(); // make glx context current + if (!valid()) { + ... set up projection exactly the same as draw ... + valid(1); // stop it from doing this next time + } + ... ok to call NON-DRAWING OpenGL code here, such as hit + detection ... +</pre> + +<p>Your main program can now create one of your windows by doing "new +MyWindow(...)". You can also use <a href=fluid.html>fluid</a>: + +<ol> +<li>Put your class definition in a MyWindow.H file. +<li>In fluid create a box object, resize & place where you want. +<li>In the control panel, fill in the "class" field with MyWindow.H. +This will make fluid produce constructors for your new class. +<li>In the "extra code" put "#include "MyWindow.H"", so that the fluid +output file will compile. +</ol> + +<p>You must put glwindow->show() in your main code after calling +show() on the window containing the gl window. + +<p><hr> +<h2>class Fl_Gl_Window : public <a href=Fl_Window.html>Fl_Window</a></h2> + +<p>An Fl_Gl_Window sets things up so OpenGL works, and also keeps an +OpenGL "context" for that window, so that changes to the lighting and +projection may be reused between redraws. Fl_Gl_Window also flushes +the OpenGL streams and swaps buffers after draw() returns. + +<p>Fl_Gl_Window::draw() is a pure virtual method. You must subclass +Fl_Gl_Window and provide an implementation for draw(). You may also +provide an implementation of draw_overlay() if you want to draw into +the overlay planes. You can avoid reinitializing the viewport and +lights and other things by checking valid() at the start of draw() and +only doing the initialization if it is false. + +<p>The draw() method can <i>only</i> use OpenGL calls. Do not attempt to +call X, any of the functions in <FL/fl_draw.H>, or glX directly. Do +not call gl_start() or gl_finish(). + +<h2>Methods:</h2> + +<h4><code>Fl_Gl_Window::Fl_Gl_Window(int W, int H, const char *l=0); +<br>Fl_Gl_Window::Fl_Gl_Window(int X, int Y, int W, int H, const char +*l=0)</code></h4><ul> + +The constructors. Fl_Gl_Window::mode() defaults to +<code>FL_RGB|FL_DOUBLE|FL_DEPTH</code>. + +<a name=mode> +</ul><h4><code>const int Fl_Gl_Window::mode() const; +<br>int Fl_Gl_Window::mode(int);</code></h4><ul> + +Set or change the OpenGL capabilites of the window. The value can be +any of the following or'd together: + +<p><ul> +<li><code>FL_RGB</code> - Color (not indexed) +<li><code>FL_RGB8</code> - Color with at least 8 bits of each color +<li><code>FL_INDEX</code> - Indexed mode +<li><code>FL_SINGLE</code> - not double buffered +<li><code>FL_DOUBLE</code> - double buffered +<li><code>FL_ACCUM</code> - accumulation buffer +<li><code>FL_ALPHA</code> - alpha channel in color +<li><code>FL_DEPTH</code> - depth buffer +<li><code>FL_STENCIL</code> - stencil buffer +<li><code>FL_MULTISAMPLE</code> - multisample antialiasing +</ul> + +<p><code>FL_RGB</code> and <code>FL_SINGLE</code> have a +value of zero, they are "on" <i>unless</i> you give +<code>FL_INDEX</code> or <code>FL_DOUBLE</code>. + +<p>If the desired combination cannot be done, fltk will try turning off +the <code>FL_MULTISAMPLE</code>. If this also fails show() will call +Fl::error() and not show the window. + +<p>You can change the mode while the window is displayed. This +is most useful for turning double-buffering on and off. <i>Under +X this will cause the old X window to be destroyed and a new one +created. If this is a top-level window this will unfortunately also +cause the window to blink, raise to the top, and be de-iconized, and +the xid() will change, possibly breaking other code. It is best to +make the GL window a child of another window if you wish to do this!</i> + +</ul><h4><code>int Fl_Gl_Window::mode(const int *);</code></h4><ul> + +<p><i>This call only works on systems using glX.</i> This value is +passed unchanged to glXChooseVisual(), superceeding the value +calculated from mode(int). See "man glXChooseVisual" if you wish to +construct your own mode. Fltk assummes that the pointer is to static +const data, and caches the pointer with the found visual. +glXChooseVisual is not called until show() or can_do() +is called. To restore the use of mode(int), call +<code>mode((int*)0)</code>. + +</ul><h4><code>static int Fl_Gl_Window::can_do(int); +<br>static int Fl_Gl_Window::can_do(const int *mode); +<br>int Fl_Gl_Window::can_do() const;</code></h4><ul> + +Returns non-zero if show() will not call Fl::error() if called with +the given or current mode. + +</ul><h4><code>char Fl_Gl_Window::valid() const; +<br>void Fl_Gl_Window::invalidate(); +<br>void Fl_Gl_Window::valid(char i);</code></h4><ul> + +<code>Fl_Gl_Window::valid()</code> is turned off when fltk creates a +new context for this window and by the window resizing, and is turned +on <i>after</i> draw() is called. You can use this inside your draw() +method to avoid unneccessarily initializing the OpenGL context. Just +do this: + +<ul><pre><code>void mywindow::draw() { + if (!valid()) { + glViewport(0,0,w(),h()); + glFrustum(...); + glLight(...); + ...other initilization... + } + ... draw your geometry here ... +} +</code></pre></ul> + +<p>You can also turn valid() off yourself (for instance if you know +the current projection has changed). To do this call +<code>invalidate()</code>. + +<p>You can turn valid() on by calling valid(1). You should only do +this after fixing the transformation inside a draw() or after +make_current(). This is done automatically after draw() returns. + +</ul><h4><code>void Fl_Gl_Window::ortho();</code></h4><ul> + +Set the projection so 0,0 is in the lower left of the window and each +pixel is 1 unit wide/tall. If you are drawing 2D images, your draw() +method may want to call this if valid() is false. + +</ul><h4><code>void Fl_Gl_Window::make_current(); +<br>void Fl_Gl_Window::make_overlay_current(); +<br>void Fl_Gl_Window::swap_buffers();</code></h4><ul> + +These functions can be used to set the current GL context to a window +and draw into it incrementally, rather than using the draw() method. +You will also need to call make_current() to do OpenGL feedback or hit +detection in response to events. After calling make_current(), be +sure to test valid(), and if false, initialize the transformation and +call valid(1). + +</ul><h4><code>void Fl_Gl_Window::hide(); +<br>Fl_Gl_Window::~Fl_Gl_Window();</code></h4><ul> + +Hiding the window or destroying it also destroys the OpenGL context it +uses. + +</ul><h2>Fl_Gl_Window overlay</h2> + +GL hardware typically provides some overlay bit planes, which are very +useful for drawing UI controls atop your 3D graphics. If the overlay +hardware is not provided, fltk tries to simulate the overlay, this works +pretty well if your graphics are double buffered, but not very well +for single-buffered. + +</ul><h4><code>int Fl_Gl_Window::can_do_overlay();</code></h4><ul> + +Returns true if the hardware overlay is possible. If this is false, +fltk will try to simulate the overlay, with significant loss of update +speed. Calling this will cause fltk to open the display. + +</ul><h4><code>void Fl_Gl_Window::redraw_overlay();</code></h4><ul> + +Call this if what is drawn in the overlay needs to change, this will +cause draw_overlay to be called at a later time. Initially the +overlay is clear, if you want the window to display something in the +overlay when it first appears, you must call this immediately after +you show() your window. + +</ul><h4><code>virtual void Fl_Gl_Window::draw_overlay();</code></h4><ul> + +You must implement this virtual function if you want to draw into the +overlay. The overlay is cleared before this is called. You should +draw anything that is not clear, using OpenGl. You must use +gl_color(i) to choose colors (it allocates them from the colormap +using system-specific calls), and remember that you are in an indexed +OpenGL mode and drawing anything other than flat-shaded will probably +not work. + +<p>Both this function and Fl_Gl_Window::draw() must check +Fl_Gl_Window::valid(), and set the same transformation. If you don't +your code may not work on other systems. Depending on the OS, and on +whether overlays are real or simulated, the OpenGL context may be the +same or different between the overlay and main window. + +</ul><p><hr> +<a name=gl_start> +<h2>Using OpenGL in normal Fltk windows</h2> + +<p>You can put OpenGL code into an <a +href=subclass.html#draw>Fl_Widget::draw()</a> method or into the code +for a <a href=Boxtypes.html>boxtype</a> or other places, with some care. + +<p>Most important, before you show <i>any</i> windows (including those +that don't have OpenGL drawing) you must initialize fltk/X so that it +knows it is going to use OpenGL. You may use any of the symbols +described for <a href=#mode>Fl_Gl_Window::mode()</a> to describe how +you intend to use OpenGL: + +<ul><p><code> Fl::gl_visual(FL_RGB);</code></ul> + +<p>You can then put OpenGL drawing code anywhere you can draw normally +by surrounding it with: + +<ul><p><code>gl_start();</code><br> +<i>... put your OpenGL code here ...</i><br> +<code>gl_finish();</code></ul> + +<p>gl_start() and gl_finish() set up a GL context with an orthographic +projection so that 0,0 is the lower-left corner of the window and each +pixel is one unit. The current clipping is reproduced with OpenGL +scissor commands. These also synchronize the OpenGL graphics stream +with the drawing done by other X or fltk functions. + +<p>The same context is reused each time. If your code changes the +projection transformation or anything else you should use glPush/glPop +to put the state back before calling gl_finish(). + +<p>You may want to use <code>Fl_Window::current()->h()</code> to get +the drawable height so you can flip the coordinate system. + +<p>Unfortunately there are a bunch of limitations you must adhere to for +maximum portability:<ul> + +<li>You must choose a default visual with <a +href=Fl.html#gl_visual>Fl::gl_visual()</a>. + +<li>You cannot pass FL_DOUBLE to Fl::gl_visual(). + +<li>You cannot use Fl_Double_Window (or Fl_Overlay_Window). + +</ul> + +<p>Do <i>not</i> call gl_start()/gl_finish() when drawing an +Fl_Gl_Window! + +</ul><p><hr> +<a name=drawing> +<h2>OpenGL drawing functions +<br>#include <FL/gl_draw.H></h2> + +Fltk provides some useful gl drawing functions. They can be freely +mixed with any OpenGL calls, and are defined by including <FL/gl.H> +(which you should include instead of the OpenGL header <GL/gl.h>). + +</ul><h4><code>void gl_color(Fl_Color);</code></h4><ul> + +Set the current color to a fltk color index. <i>For color-index modes +it will use fl_xpixel(c), which is only right if this window uses the +default X colormap</i>. + +</ul><h4><code>void gl_rect(int x,int y,int w,int h); +<br>void gl_rectf(int x,int y,int w,int h);</code></h4><ul> + +Outline or fill a rectangle with the current color. If ortho() has +been called, then the rectangle will exactly fill the pixel rectangle +passed. + +</ul><h4><code>void gl_font(Fl_Font fontid, int size);</code></h4><ul> + +Set the "current GL font" to the same font you get by calling +<a href=Draw.html#fl_font>fl_font()</a>. + +</ul><h4><code>int gl_height(); +<br>int gl_descent(); +<br>float gl_width(const char *); +<br>float gl_width(const char *, int n); +<br>float gl_width(uchar);</code></h4><ul> + +Return information about the current GL font. + +</ul><h4><code>void gl_draw(const char *); +<br>void gl_draw(const char *, int n);</code></h4><ul> + +Draw a null-terminated string or an array of <i>n</i> characters in +the current GL font at the current glRasterPos. + +</ul><h4><code>void gl_draw(const char *, int x, int y); +<br>void gl_draw(const char *, int n, int x, int y);</code></h4><ul> + +Draw a null-terminated string or an array of <i>n</i> characters in +the current GL font at the given position. + +</ul><h4><code>void gl_draw(const char *, int x, int y, int w, int h, Fl_Align);</code></h4><ul> + +Draw a string formatted into a box, with newlines and tabs expanded, +other control characters changed to ^X, and aligned with the edges or +center. Exactly the same output as <a href=Draw.html#fl_draw>fl_draw()</a>. + +</ul> +<p><a href = index.html>(back to contents)</a> +<title>Fltk example: shape.C</title> +<h2>shape.C</h2> + +<p>Of course GL is no fun unless you can draw your own graphics. This +is done with a subclass that you create: + +<p><img src = shape.C.gif align=top> + +<pre> +#include <FL/Fl.H> +#include <FL/Fl_Window.H> +#include <FL/Fl_Hor_Slider.H> +#include <FL/math.h> +#include <FL/gl.h> +#include <FL/Fl_Gl_Window.H> + +class shape_window : public Fl_Gl_Window { + void draw(); +public: + int sides; + shape_window(int x,int y,int w,int h,const char *l=0); +}; + +shape_window::shape_window(int x,int y,int w,int h,const char *l) : +Fl_Gl_Window(x,y,w,h,l) { + sides = 3; +} + +void shape_window::draw() { + // the valid() property may be used to avoid reinitializing your + // GL transformation for each redraw: + if (!valid()) { + valid(1); + glLoadIdentity(); + glViewport(0,0,w(),h()); + } + // draw an amazing graphic: + glClear(GL_COLOR_BUFFER_BIT); + glColor3f(.5,.6,.7); + glBegin(GL_POLYGON); + for (int i=0; i<sides; i++) { + double ang = i*2*M_PI/sides; + glVertex3f(cos(ang),sin(ang),0); + } + glEnd(); +} + +// when you change the data, as in this callback, you must call redraw(): +void sides_cb(Fl_Widget *o, void *p) { + shape_window *sw = (shape_window *)p; + sw->sides = int(((Fl_Slider *)o)->value()); + sw->redraw(); +} + +int main(int argc, char **argv) { + + Fl_Window window(300, 330); + + shape_window sw(10, 10, 280, 280); + window.resizable(&sw); + + Fl_Hor_Slider slider(50, 295, window.w()-60, 30, "Sides:"); + slider.align(FL_ALIGN_LEFT); + slider.callback(sides_cb,&sw); + slider.value(sw.sides); + slider.step(1); + slider.bounds(3,40); + + window.show(argc,argv); + + return Fl::run(); +} +</pre> + +<p>To do your own drawing, you must subclass <a +href=Fl_Gl_Window.html>Fl_Gl_Window</a>. The virtual method <a +href=subclass.html#draw>draw()</a> is called when the window should +update. You can only draw into the window inside a draw() method. +You call the method <a href=Fl_Widget.html#redraw>redraw()</a> on the +window to indicate that draw() needs to be called. It won't actually +be called until <a href=Fl.html#wait>Fl::wait()</a> is called. + +<P>The window may be made a child of another window, as it is here. +This is done by add()ing it to a parent before you show() it. <i>If +you don't want to make a child window, be sure to end() the previous +window!</i> The Fl_Gl_Window constructor automatically does end() so +you don't accidentally add children to it. + +<p>The files <FL/math.h> and <FL/gl.h> are wrappers for the +normal header files. You should use them to port to MSWindows because +the MicroSoft header files have errors or ommisions in them. + +<p><a href = index.html>[back to contents]</a> diff --git a/documentation/osissues.html b/documentation/osissues.html new file mode 100644 index 000000000..f9cd36991 --- /dev/null +++ b/documentation/osissues.html @@ -0,0 +1,455 @@ +<HTML> +<BODY> + +<H1 ALIGN=RIGHT>F - Operating System Specific Issues</H1 + +</BODY> +</HTML> +<title>Fltk X-specific interface</title> +<h2>Fltk X-specific interface</h2> + +<b>#include <FL/x.H></b> + +<p>On Unix/X you can include this file to access fltk's X-specific +functions. Be warned that some of the structures and calls in it are +subject to change in future version of fltk. Try to avoid doing this +so your code is portable. + +<p><hr> + +<h2>Handling other X events</h2> + +<a name=add_handler> +</ul><h4><code>void Fl::add_handler(int (*f)(int));</code></h4><ul> + +Install a function to parse unrecognized events. If fltk cannot figure +out what to do with an event, it calls each of these functions (most +recent first) until one of them returns non-zero. If none of them +returns non zero then the event is ignored. + +<p>Fltk calls this for any X events it does not recognize, or X events +with a window id that fltk does not recognize. You can look at the X +event with the <a href=#fl_xevent><code>fl_xevent</code></a>. + +<p>The argument is zero for unrecognized X events. These handlers are +also called for global shortcuts and some other events that the widget +they were passed to did not handle. In this case the argument is +non-zero (for instance FL_SHORTCUT). + +<a name=fl_xevent> +</ul><h4><code>extern XEvent* fl_xvent;</code></h4><ul> + +The most current X event. + +<a name=fl_event_time> +</ul><h4><code>extern ulong fl_event_time;</code></h4><ul> + +This is the time stamp from the most recent X event that reported it +(not all do). Many X calls (like cut and paste) need this value. + +</ul><h4><code>Window fl_xid(const Fl_Window*);</code></h4><ul> + +Returns the xid for a window, or zero if not shown(). + +</ul><h4><code>Fl_Window* fl_find(ulong xid);</code></h4><ul> + +<p>Return the Fl_Window that corresponds to the given xid, or +null if not found. This uses a cache so it is slightly faster than +iterating through the windows yourself. + +</ul><h4><code>int fl_handle(const XEvent&);</code></h4><ul> + +This call allows you to supply the X events to fltk, which may allow +fltk to cooperate with another toolkit or library. The return value +is true if fltk understood the event (if the window does not belong to +fltk and the add_handler() functions all ignore it this returns +false). + +<p>Besides feeding events your code should call <a +href=Fl.html#flush>Fl::flush()</a> periodically so that fltk redraws +it's windows. + +<p>This function will call the callback functions. It will not return +until they complete. In particular if a callback pops up a modal +window (by calling <a href=utilities.html#fl_ask>fl_ask()</a>, for +instance) it will not return until the modal function returns. + +</ul> +<p><hr> + +<a name=draw> +<h2>Drawing using Xlib</h2> + +</ul><h4><code> +extern Display* fl_display;<br> +extern Window fl_window;<br> +extern GC fl_gc;<br> +extern int fl_screen;<br> +extern XVisualInfo* fl_visual;<br> +extern Colormap fl_colormap;</code></h4><ul> + +These global variables are set before Fl_Widget::draw() is called, or +by <a href=Fl_Window.html#make_current>Fl_Window::make_current()</a> +You must use them to produce Xlib calls. Don't attempt to change +them. A typical X drawing call is written like this: + +<ul><p><code>XDrawSomething(fl_display, fl_window, fl_gc, ...);</code></ul> + +<p>Other information such as the position or size of the X window can be +found by looking at <a +href=Fl_Window.html#make_current><code>Fl_Window::current()</code></a>, +which returns a pointer to the Fl_Window being drawn. + +</ul><h4><code>unsigned long fl_xpixel(Fl_Color i);</code></h4><ul> + +Returns the X pixel number used to draw the given fltk color index. +This is the X pixel that <a href=Draw.html#fl_color>fl_color(i)</a> would use. + +</ul><h4><code>unsigned long fl_xpixel(uchar r, uchar g, uchar +b);</code></h4><ul> + +Return the X pixel number used to draw the given rgb color. This is +the X pixel that <a href=Draw.html#fl_rgbcolor>fl_color(r,g,b)</a> would use. + +</ul><h4><code>extern XFontStruct* fl_xfont;</code></h4><ul> + +Points at the font selected by the most recent <a +href=Draw.html#fl_font>fl_font(font,size)</a>. This is not +necessarily the current font of fl_gc (that's not set until <a +href=Draw.html#text>fl_draw(const char*,...)</a> is called). + +</ul> + +<p><hr> + +<a name=visuals> +<h2>Changing the display, screen, or X visual</h2> + +<p>Fltk uses only a single display, screen, X visual, and X colormap. +This greatly simplifies it's internal structure and makes it much +smaller and faster. You can change which it uses by setting global +variables <i>before the first Fl_Window::show() is called</i>. +You may also want to call <a +href=Fl.html#visual>Fl::visual(int)</a>, which is a portable interface +to get a full color and/or double buffered visual. + +</ul><h4><code>int Fl::display(const char *)</code></h4><ul> + +Set which X display to use. This actually does +<code>setenv("DISPLAY", x)</code> so that child programs will +display on the same screen if called with exec(). This must be done +before the display is opened. This call is provided on MSWindows, but +it just sets the environment variable and has no other effect. + +</ul><h4><code>extern Display* fl_display;</code></h4><ul> + +The open X display. This is needed as an argument to most Xlib calls. +Don't attempt to change it! This is zero before the display is opened. + +</ul><h4><code>void fl_open_display();</code></h4><ul> + +Open the display. Does nothing if it is already open. This will make +sure <code>fl_display</code> is non-zero. You should call this if you +wish to do X calls and there is a chance that your code will be called +before the first show() of a window. + +<p>This may call Fl::abort() if there is an error opening the display. + +</ul><h4><code>void fl_close_display();</code></h4><ul> + +This closes the X connection. You do <i>not</i> need to call this to +exit, and in fact it is faster to not do so! It may be useful to call +this if you want your program to continue without the X connection. +You cannot open the display again, and probably cannot call any fltk +functions. + +</ul><h4><code>extern int fl_screen;</code></h4><ul> + +Which screen to use. This is set by fl_open_display() to the default +screen. You can change it by setting this to a different value +immediately afterwards. It can also be set by changing the last +number in the Fl::display() string: host:0,#. + +</ul><h4><code>extern XVisualInfo* fl_visual;<br> +extern Colormap fl_colormap;</code></h4><ul> + +<p>The visual and colormap that fltk will use for all windows. These +are set by fl_open_display() to the default visual and colormap. You +can change them before calling show() on the first window. Typical +code for changing the default visual: + +<ul><code><pre> +Fl::args(argc, argv); // do this first so $DISPLAY is set +fl_open_display(); +fl_visual = find_a_good_visual(fl_display, fl_screen); +if (!fl_visual) Fl::abort("No good visual"); +fl_colormap = make_a_colormap(fl_display, fl_visual->visual, fl_visual->depth); +// it is now ok to show() windows: +window->show(argc, argv); +</pre></code></ul> + +</ul> + +<p><hr> +<a name=window> +<h2>Using a subclass of Fl_Window for special X stuff</h2> + +Fltk can manage an X window on a different screen, visual and/or +colormap, you just can't use fltk's drawing routines to draw into it. +But you can write your own draw() method that uses Xlib calls only. + +<p>Fltk can also manage xid's provided by other libraries or programs, +and call those libraries when the window needs to be redrawn. + +<p>To do this, you need to make a subclass of <a +href=Fl_Window.html>Fl_Window</a> and override some of these virtual +functions: + +</ul><h4><code>virtual void Fl_Window::show()</code></h4><ul> + +<p>If the window is already shown() this must cause it to be raised, +this can usually be done by calling Fl_Window::show(). If not shown() +your implementation must call either Fl_X::set_xid() or +Fl_X::make_xid(): + +<h4><code>Fl_X* Fl_X::set_xid(Fl_Window*, Window xid);</code></h4><ul> + +Allocate a hidden structure called an Fl_X, put the xid into it, and +set a pointer to it from the Fl_Window. This causes +Fl_Window::shown() to return true. + +</ul><h4><code>void Fl_X::make_xid(Fl_Window*, XVisualInfo* = +fl_visual, Colormap = fl_colormap);</code></h4><ul> + +This static method does the most onerous parts of creating an X window, +including setting the label, resize limitations, etc. It then does +set_xid with this new window and maps the window. + +</ul> + +<p>Example: + +<pre> +void MyWindow::show() { + if (shown()) {Fl_Window::show(); return;} // you must do this! + fl_open_display(); // necessary if this is first window + // we only calcualte the necessary visual & colormap once: + static XVisualInfo *visual; + static Colormap colormap; + if (!visual) { + visual = figure_out_visual(); + colormap = XCreateColormap(fl_display, RootWindow(fl_display,fl_screen), + vis->visual, AllocNone); + } + Fl_X::make_xid(this, visual, colormap); +} +</pre> + +</ul><h4><code>virtual void Fl_Window::flush()</code></h4><ul> + +This virtual function is called by Fl::flush() to update the window. +For fltk's own windows it does this by setting the global variables +fl_window and fl_gc and then calling the draw() method. For your own +windows you might just want to put all the drawing code in here. + +<p>The X region that is a combination of all damage() calls done so +far is in <code>Fl_X::i(this)->region</code>. If null then +you should redraw the entire window. The undocumented function +<code>fl_clip_region(XRegion)</code> will initialize the fl clip stack +with a region or null for no clipping. You must set region to null +afterwards as fl_clip_region() now owns it and will delete it when +done. + +<p>If <code>damage()==2</code> then only X expose events have +happened. This may be useful if you have an undamaged image (such as +a backing buffer) around. + +<p>Here is a sample where an undamaged image is kept somewhere: + +<pre> +void MyWindow::flush() { + fl_clip_region(Fl_X::i(this)->region); + Fl_X::i(this)->region = 0; + if (damage() != 2) {... draw things into backing store ...} + ... copy backing store to window ... +} +</pre> + +</ul><h4><code>virtual void Fl_Window::hide()</code></h4><ul> + +Destroy the window server copy of the window. Usually you will +destroy contexts, pixmaps, or other resources used by the window, and +then call Fl_Window::hide() to get rid of the main window identified +by xid(). If you override this, you must also override the destructor +as shown: + +<pre> +void MyWindow::hide() { + if (mypixmap) { + XFreePixmap(fl_display,mypixmap); + mypixmap = 0; + } + Fl_Window::hide(); // you must call this +} +</pre> + +</ul><h4><code>virtual void Fl_Window::~Fl_Window()</code></h4><ul> + +Because of the way C++ works, if you override hide() you <i>must</i> +override the destructor as well (otherwise only the base class hide() +is called): + +<pre> +MyWindow::~MyWindow() { + hide(); +} +</pre> + +</ul> + +<p><a href = index.html>(back to contents)</a> +<title>Fltk MSWindows-specific interface</title> +<h2>#include <FL/x.H><br> +Fltk MSWindows-specific interface</h2> + +The <FL/x.H> header file defines the interface to fltk's +MSWindows-specific functions. Be warned that some of the structures +and calls in it are subject to change in future version of fltk. Try +to avoid doing this so your code is portable. + +<p><hr> + +<h2>Handling other MSWindows messages</h2> + +<p>A single WNDCLASSEX called "FLTK" is created. All +Fl_Windows are of this class. This window class is created the first +time Fl_Window::show() is called. + +<p>You can probably combine fltk with other libraries that make their +own MSWindows window classes. The easiest way is to call Fl::wait(), it +will call DispatchMessage for all messages to the other windows. If +necessary you can let the other library take over (as long as it calls +DispatchMessage()), but you will have to arrange for the function +Fl::flush() to be called regularily (otherwise widgets will not +update), and timeouts and the idle function will not work. + +<a name=fl_msg> +</ul><h4><code>extern MSG fl_msg;</code></h4><ul> + +The most recent message read by GetMessage (which is called by +<a href=Fl.html#wait>Fl::wait()</a>. This may not be the most recent +message sent to an fltk window, because silly MSWindows calls the +handle procedures directly for some events (sigh). + +<a name=add_handler> +</ul><h4><code>void Fl::add_handler(int (*f)(int));</code></h4><ul> + +Install a function to parse unrecognized messages sent to fltk +windows. If fltk cannot figure out what to do with a message, it +calls each of these functions (most recent first) until one of them +returns non-zero. The argument passed to the fuctions is zero. If +all the handlers return zero then fltk calls DefWindowProc(...). + +</ul><h4><code>HWND fl_xid(const Fl_Window*);</code></h4><ul> + +Returns the window handle for a Fl_Window, or zero if not shown(). + +</ul><h4><code>Fl_Window* fl_find(HWND xid)</code></h4><ul> + +<p>Return the Fl_Window that corresponds to the given window handle, +or null if not found. This uses a cache so it is slightly faster than +iterating through the windows yourself. + +</ul> + +<p><hr> + +<a name=gdi> +<h2>Drawing things using the MSWindows GDI</h2> + +<p>When the virtual function Fl_Widget::draw() is called, fltk has +stashed in some global variables all the silly extra arguments you +need to make a proper GDI call. These are: + +</ul><h4><code> +extern HINSTANCE fl_display;<br> +extern HWND fl_window;<br> +extern HDC fl_gc;<br> +COLORREF fl_RGB();<br> +HPEN fl_pen();<br> +HBRUSH fl_brush();</code></h4><ul> + +These global variables are set before draw() is called, or by <a +href=Fl_Window.html#make_current>Fl_Window::make_current()</a> You can +refer to them when needed to produce GDI calls. Don't attempt to +change them. The functions return GDI objects for the current color +set by fl_color(), these are created as needed and cached. A typical +GDI drawing call is written like this: + +<ul><p><code>DrawSomething(fl_gc, ..., fl_brush());</code></ul> + +<p>It may also be useful to refer to <a +href=Fl_Window.html#make_current><code>Fl_Window::current()</code></a> +to get the window's size or position. + +</ul> +<p><hr> +<h2>How to not get a MSDOS console window</h2> + +MSWindows has a really stupid mode switch stored in the executables that +controls whether or not to make a console window (hint to Mr Gates: +why not leave it hidden until the program prints something?). + +<p>To not produce a "console" window when you run your program add the +following secret incantation to the Micro$oft linker: + +<p><pre> /SUBSYSTEM:WINDOWS /ENTRY:mainCRTStartup</pre> + +<p>Unfortunately this seems to completely disable stdin/stdout, even +if you run the program from a console. So don't do this until you +have debugged your program! + +<p><hr> +<h2>Other hints</h2> + +<p>I use capital C as the extension for c++ source code, for instace +for Fluid output. Unfortunately there is no way to convince VC++ to +use this except to tell it to compile *everything* using C++ by +putting the switch "/TP" in the options. This makes it impossible to +combine old C code and fltk code. + +<p><hr> +<h2>Known bugs</h2> + +<p>If program is deactivated, Fl::wait() does not return until it is +activated again, even though many events are delivered to the program. +This can cause idle background processes to stop unexpectedly. This +also happens while the user is dragging or resizing windows or +otherwise holding the mouse down. I was forced to remove most of the +efficiency fltk uses for redrawing in order to get windows to update +while being moved. This is a design error in MSWindows and probably +impossible to get around. + +<p>Fl_Gl_Window::can_do_overlay() returns true until the first time it +attempts to draw an overlay, and then correctly returns whether or not +there is overlay hardware. + +<p>Cut text contains ^J rather than ^M^J to break lines. This is a +feature, not a bug. + +<p>I can't seem to get SetCapture (used by Fl::grab()) to work, and I +can't find a way to stop the main window title from turning gray while +menus are popped up. + +<p>glpuzzle program does not animate unless you resize it first. Unknown why. + +<p>Fl_Window::fullscreen() not implemented (should take over the screen +without a title bar). Currently does maximize instead. + +<p>Import .bmp files into fluid. Wonko has the specs. + +<p>Can't set icon of windows. + + + + diff --git a/documentation/positioner.gif b/documentation/positioner.gif Binary files differnew file mode 100644 index 000000000..ba9d2694d --- /dev/null +++ b/documentation/positioner.gif diff --git a/documentation/preface.html b/documentation/preface.html new file mode 100644 index 000000000..5be3d0f99 --- /dev/null +++ b/documentation/preface.html @@ -0,0 +1,75 @@ +<HTML> +<HEAD> + <META NAME="Author" CONTENT="Michael Sweet"> + <META NAME="Copyright" CONTENT="Copyright 1998 by Bill Spizak and Others."> + <META NAME="DocNumber" CONTENT="Revision 0"> + <TITLE>FLTK 1.0 Programming Manual</TITLE> +</HEAD> +<BODY> + +<H1 ALIGN=RIGHT>Preface</H1> + +This manual describes the Fast Light Tool Kit ("FLTK") version 1.0, a C++ Graphical User Interface ("GUI") toolkit for UNIX and Microsoft Windows. Each of the chapters +in this manual is designed as a tutorial for using FLTK, while the appendices provide +a convenient reference for all FLTK widgets, functions, and operating system +interfaces. + +<H2>Organization</H2> + +This manual is organized into the following chapters and appendices: + +<UL> + <LI><A HREF="#intro">Chapter 1 - Introduction to FLTK</A> + <LI><A HREF="#basics">Chapter 2 - FLTK Basics</A> + <LI><A HREF="#common">Chapter 3 - Common Widgets and Attributes</A> + <LI><A HREF="#editor">Chapter 4 - Designing a Simple Text Editor</A> + <LI><A HREF="#subclasseing">Chapter 5 - Extending and Adding Widgets</A> + <LI><A HREF="#fluid">Chapter 6 - Programming With FLUID</A> + <LI><A HREF="#opengl">Chapter 7 - Using OpenGL</A> + <LI><A HREF="#widgets">Appendix A - Widget Reference</A> + <LI><A HREF="#functions">Appendix B - Function Reference</A> + <LI><A HREF="#enumerations">Appendix C - Enumeration Reference</A> + <LI><A HREF="#glut">Appendix D - GLUT Compatibility</A> + <LI><A HREF="#forms">Appendix E - Forms Compatibility</A> + <LI><A HREF="#license">Appendix F - Software License</A> +</UL> + +<H2>Conventions</H2> + +The following typeface conventions are used in this manual: + +<UL> + + <LI>Function and constant names are shown in <B><TT>bold courier type</TT></B> + + <LI>Code samples and commands are shown in <TT>regular courier type</TT> + +</UL> + +<H2>Abbreviations</H2> + +The following abbreviations are used in this manual: + +<DL> + <DT>X11</DT> + <DD>The X Window System version 11.</DD> + + <DT>Xlib</DT> + <DD>The X Window System interface library.</DD> + + <DT>WIN32</DT> + <DD>The Microsoft Windows 32-bit Application Programmer's Interface.</DD> +</DL> + +<H2>Copyrights and Trademarks</H2> + +FLTK is Copyright 1998 by Bill Spitzak and others. Use and distribution of FLTK is +governed by the GNU Library General Public License, located in +<A HREF=#license>Appendix D</A>. + +<P>UNIX is a registered trademark of the X Open Group, Inc. Microsoft and Windows are +registered trademarks of Microsoft Corporation. OpenGL is a registered trademark +of Silicon Graphics, Inc. + +</BODY> +</HTML> diff --git a/documentation/resizebox1.gif b/documentation/resizebox1.gif Binary files differnew file mode 100644 index 000000000..c5e8c300b --- /dev/null +++ b/documentation/resizebox1.gif diff --git a/documentation/resizebox2.gif b/documentation/resizebox2.gif Binary files differnew file mode 100644 index 000000000..2083afd0d --- /dev/null +++ b/documentation/resizebox2.gif diff --git a/documentation/round_clock.gif b/documentation/round_clock.gif Binary files differnew file mode 100644 index 000000000..982f084b6 --- /dev/null +++ b/documentation/round_clock.gif diff --git a/documentation/scrollbar.gif b/documentation/scrollbar.gif Binary files differnew file mode 100644 index 000000000..3b548a4d0 --- /dev/null +++ b/documentation/scrollbar.gif diff --git a/documentation/shape.C.gif b/documentation/shape.C.gif Binary files differnew file mode 100644 index 000000000..ebed8a6f2 --- /dev/null +++ b/documentation/shape.C.gif diff --git a/documentation/slider.gif b/documentation/slider.gif Binary files differnew file mode 100644 index 000000000..af3e09863 --- /dev/null +++ b/documentation/slider.gif diff --git a/documentation/subclassing.html b/documentation/subclassing.html new file mode 100644 index 000000000..414cca67b --- /dev/null +++ b/documentation/subclassing.html @@ -0,0 +1,519 @@ +<HTML> +<BODY> + +<H1 ALIGN=RIGHT><A NAME="subclassing">5 - Adding and Extending Widgets</A></H1> + +This chapter describes how to add your own widgets or extend existing widgets in FLTK. + +<H2>Subclassing</H2> + +<H2>Adding Syntax Highlighting to the Fl_Input Widget</H2> + +<H2>Drawing Functions</H2> + +<H3>Lines, Rectangles, and Curves, Oh, My!</H3> + +<H3>Colors</H3> + +<H3>Fonts</H3> + +<H3>Images</H3> + +<H2><A NAME="Fl_Table">Writing a Table Widget</A></H2> + +<H3>Methods</H3> + +<H3>Cut and Paste Support</H3> + +</BODY> +</HTML> +<title>Cut & paste</title> +<h2>Cut & paste</h2> + +Fltk provides routines to cut and paste ASCII text (in the future this +may be UTF-8) between applications. It may be possible to cut/paste +non-ascii data under X by using <a +href=events.html#add_handler>Fl::add_handler()</a>. + +</ul><h4><code>void Fl::paste(Fl_Widget *receiver)</code></h4><ul> + +<P>Set things up so the receiver widget will be called with an <a +href=events.html#paste>FL_PASTE</a> event some time in the future. +The reciever should be prepared to be called <i>directly</i> by this, +or for it to happen <i>later</i>, or possibly <i>not at all</i>. This +allows the window system to take as long as necessary to retrieve the +paste buffer (or even to screw up completely) without complex and +error-prone synchronization code in fltk. + +</ul><h4><code>void Fl::selection(Fl_Widget *owner, const char *stuff, int len); +</code></h4><ul> + +<p>Change the current selection. The block of text is copied to an +internal buffer by Fltk (be careful if doing this in response to an +FL_PASTE as this <i>may</i> be the same buffer returned by +event_text()). The selection_owner is set to the passed owner +(possibly sending FL_SELECTIONCLEAR to the previous owner). + +</ul><h4><code>const char* Fl::selection(); +<br>int Fl::selection_length();</code></h4><ul> + +You can look at the buffer containing the current selection. Contents +of this buffer are undefined if this program does not own the X +selection. + +</ul><h4><code>Fl_Widget *Fl::selection_owner() const; +<br>void Fl::selection_owner(Fl_Widget *);</code></h4><ul> + +<p>The single-argument selection_owner(x) call can be used to move the +selection to another widget or to set the owner to NULL, without +changing the actual text of the selection. FL_SELECTIONCLEAR is sent +to the old selection owner, if any. + +</ul> + +<p><i>Copying the buffer every time the selection is changed is +obviously wasteful, especially for large selections. I expect an +interface will be added in a future version to allow the selection to +be made by a callback function. The current interface will be +emulated on top of this.</i> + +<title>Making a subclass of Fl_Widget</title> +</ul><h2>Making a subclass of Fl_Widget</h2> + +<p>Your subclasses can directly descend from Fl_Widget or any +subclass of Fl_Widget. Fl_Widget has only four virtual methods, and +overriding some or all of these may be necessary. + +<p>Parts of this document: + +<ul> + +<li><a href=#constructor>Constructing your Fl_Widget</a> + +<li><a href=#protected>Protected methods of Fl_Widget</a> + +<li>Virtual functions to override: + +<ul> + +<li><code><a href=#handle>int Fl_Widget::handle(int +event);</a></code> + +<li><code><a href=#draw>void Fl_Widget::draw();</a></code> + +<li><code><a href=#resize>void +Fl_Widget::resize(int,int,int,int);</a></code> + +<li><code><a href=#destructor>Fl_Widget::~Fl_Widget();</a></code> + +</ul> + +<li><a href=#composite>Making a Composite/Group Widget</a> + +<li><a href=#window>Making a subclass of Fl_Window</a> + +</ul> + +<a name=constructor> +<h2>Constructing your Fl_Widget</h2> + +I recommend your constructor be of this form: + +<p><pre> + Class(int x, int y, int w, int h, const char* label = 0); +</pre> + +<p>This will allow the class name to be typed into <a +href=fluid.html>fluid</a> and it will produce the correct call. + +<p>The constructor must call the constructor for the base class and +pass the same arguments. Fl_Widget's protected constructor sets x(), +y(), w(), h(), and label() to the passed values and initializes the +other instance variables to: + +<p><pre> + type(0); + box(FL_NO_BOX); + color(FL_GRAY); + selection_color(FL_GRAY); + labeltype(FL_NORMAL_LABEL); + labelstyle(FL_NORMAL_STYLE); + labelsize(FL_NORMAL_SIZE); + labelcolor(FL_BLACK); + align(FL_ALIGN_CENTER); + callback(default_callback,0); + flags(ACTIVE|VISIBLE); +</pre> + +<a name=protected> +<h2>Protected methods of Fl_Widget</h2> + +<p>These methods are provided for subclasses to use. + +</ul><h4><code>uchar Fl_Widget::type() const; +<br>void Fl_Widget::type(uchar); +</code></h4><ul> + +The property Fl_Widget::type() can return an arbitrary 8-bit +identifier, and can be set with the protected method type(uchar). +This value had to be provided for Forms compatability, but you can use +it for any purpose you want. Try to keep the value less than 100 to +not interfere with reserved values. + +<p>Fltk does not use RTTI (Run Time Typing Infomation), to enhance +portability. But this may change in the near future if RTTI becomes +standard everywhere. + +<p>If you don't have RTTI you can use the clumsy fltk mechanisim, by +having type() have a unique value. These unique values must be +greater than the symbol FL_RESERVED_TYPE (which is 100). Grep through +the header files for "FL_RESERVED_TYPE" to find an unused number. If +you make a subclass of Fl_Group you must use FL_GROUP+n, and if you +make a subclass of Fl_Window you must use FL_WINDOW+n (in both cases n +is in the range 1-7). + +<a name=test_shortcut> +</ul><h4><code>void Fl_Widget::set_flag(SHORTCUT_LABEL);</code></h4><ul> + +If your constructor calls this it modifies draw_label() so that '&' +characters cause an underscore to be printed under the next letter. + +</ul><h4><code>int Fl_Widget::test_shortcut() const;<br> +static int Fl_Widget::test_shortcut(const char *);</code></h4><ul> + +The first version tests Fl_Widget::label() against the current event +(which should be a FL_SHORTCUT event). If the label contains a '&' +character and the character after it matches the key press, this +returns true. This returns false if the SHORTCUT_LABEL flag is off, +if the label is null or does not have a '&' character in it, or if the +keypress does not match the character. + +<p>The second version lets you do this test to an arbitrary string. + +</ul><h4><code>void Fl_Widget::x(short); +<br>void Fl_Widget::y(short); +<br>void Fl_Widget::w(short); +<br>void Fl_Widget::h(short);</code></h4><ul> + +You can directly clobber the values for <a +href=Fl_Widget.html#xywh>x(), y(), w(), and h()</a>. Make sure you +know what you are doing. This is most useful for temporarily +replacing the values before calling handle() or draw() on the base +class to "fool" it into working in a different area. + +<a name=damage> +</ul><h4><code>void Fl_Widget::damage(uchar mask);</code></h4><ul> + +Indicate that a partial update of the object is needed. The bits in +mask are or'd into damage(). Your draw() routine can examine these +bits to limit what it is drawing. The public method +Fl_Widget::redraw() simply does Fl_Widget::damage(-1). + +</ul><h4><code>void Fl_Widget::damage(uchar mask,int x,int y,int w,int +h);</code></h4><ul> + +Indicate that a region is damaged. If only these calls are done in a +window (no calls to damage(n)) then fltk will clip to the union of all +these calls before drawing anything. This can greatly speed up +incremental displays. The mask bits are or'd into damage() (unless +this is a Fl_Window, in which case they are forced to the value 6 for +internal reasons). + +</ul><h4><code>void Fl_Widget::clear_damage(uchar value = 0);</code></h4><ul> + +Directly set damage() to the passed value. This is provided for +kludges only. + +</ul><h4><code>uchar Fl_Widget::damage()</code></h4><ul> + +Return the bitwise-or of all damage(n) calls done since the last +draw(). The public method redraw() does damage(-1), but the +implementation of your widget can call the private damage(n). + +</ul><h4><code>void Fl_Widget::set_visible(); +<br>void Fl_Widget::clear_visible();</code></h4><ul> + +Fast inline versions of Fl_Widget::hide() and Fl_Widget::show(). +These do not send the FL_HIDE and FL_SHOW events to the widget. + +</ul><h4><code>void Fl_Widget::draw_box() const ;</code></h4><ul> + +Draw this widget's box(), using the dimensions of the widget. + +</ul><h4><code>void Fl_Widget::draw_box(Fl_Boxtype b,ulong c) const +;</code></h4><ul> + +Pretend the box()==b and the color()==c and draw this widget's box. + +<a name=draw_label> +</ul><h4><code>void Fl_Widget::draw_label() const ;</code></h4><ul> + +This is the usual function for a draw() method to call to draw the +widget's label. It does not draw the label if it is supposed to be +outside the box (on the assumption that the enclosing group will draw +those labels). + +</ul><h4><code>void Fl_Widget::draw_label(int x,int y,int w,int h) const +;</code></h4><ul> + +Do the same thing except use the passed bounding box. This is useful +so "centered" labels are aligned with some feature, such as a moving +slider. + +</ul><h4><code>void Fl_Widget::draw_label(int x,int y,int w,int +h,Fl_Align align) const ;</code></h4><ul> + +Draw the label anywhere. It acts as though FL_ALIGN_INSIDE has been +forced on, the label will appear inside the passed bounding box. This +is designed for parent groups to draw labels with. + +</ul> +<a name=handle> +<h2>virtual int Fl_Widget::handle()</h2> + +The virtual method <b><code>int Fl_Widget::handle(int +event)</code></b> is called to handle each event passed to the widget. +It can:<ul> + +<li>Change the state of the widget. + +<li>Call <a href=Fl_Widget.html>Fl_Widget::redraw()</a> if the widget +needs to be redisplayed. + +<li>Call <a href=#damage>Fl_Widget::damage(n)</a> if the widget needs +a partial-update (assumming you provide support for this in your +Fl_Widget::draw() method). + +<li>Call <a href=Fl_Widget.html>Fl_Widget::do_callback()</a> if a +callback should be generated. + +<li>Call Fl_Widget::handle() on child widgets. + +</ul> + +<p>Events are identified the small integer argument. Other +information about the most recent event is stored in static locations +and aquired by calling <a href=events.html><code>Fl::event_*()</code></a>. +This other information remains valid until another event is read from +the X server. + +<p>Here is a sample Fl_Widget::handle(), for a widget that acts as a +pushbutton and also accepts the keystroke 'x' to cause the callback: + +<ul><pre>int Fl_Pushbutton::handle(int event) { + switch(event) { + case FL_PUSH: + highlight = 1; redraw(); + return 1; + case FL_DRAG: + {int t = Fl::event_inside(this); + if (t != highlight) {highlight = t; redraw();}} + return 1; + case FL_RELEASE: + if (highlight) { + highlight = 0; redraw(); + do_callback(); + // never do anything after a callback, so that the callback + // may delete the widget! + } + return 1; + case FL_SHORTCUT: + if (Fl::event_key() == 'x') {do_callback(); return 1;} + return 0; + default: + return 0; + } + } +} +</pre></ul> + +<p>You must return non-zero if your handle() method used the event. +If you return zero it indicates to the parent that it can try sending +another widget the event. + +<p>It looks like it is best to make the handle() method public. + +<a name=draw> +<h2>virtual void Fl_Widget::draw()</h2> + +<p>The virtual method Fl_Widget::draw() is called when fltk wants you +to redraw your widget. It will be called if and only if damage() is +non-zero, and damage() will be cleared to zero after it returns. +draw() should be declared protected, so that subclasses may call it +but it can't be called from non-drawing code. + +<p>damage() contains the bitwise-or of all the damage(n) calls to this +widget since it was last drawn. This can be used for minimal update, +by only redrawing the parts whose bits are set. Fltk will turn +<i>all</i> the bits on if it thinks the entire widget must be redrawn +(for instance due to an expose event). It is easiest to program to +handle this by pretending a bit (usually damage()&128) draw the +non-minimal-update parts of your widget (such as the box()). + +<p>Expose events (and the above damage(b,x,y,w,h)) will cause draw() +to be called with fltk's <a href=Draw.html#clipping>clipping</a> +turned on. You can greatly speed up redrawing in some cases by +testing <code>fl_clipped</code> and <code>fl_current_clip</code> +and skipping invisible parts. + +<p>The functions you can use to draw are described in <a +href=Draw.html><FL/fl_draw.H></a> or any of the protected +Fl_Widget::draw_* methods described above. + +<a name=resize> +<h2>virtual void Fl_Widget::resize(int,int,int,int);</h2> + +This is called when the widget is being resized or moved. The +arguments are the new position, width, and height. x(), y(), w(), and +h() still return the old size. You must call resize() on your +base class with the same arguments to get the widget size to actually +change. + +<p>This should <i>not</i> call redraw(), at least if only the x() and +y() change. This is because group objects like <a +href=Fl_Scroll.html>Fl_Scroll</a> may have a more efficient way of +drawing the new position. + +<p>It may be useful to refer to the size the widget was constructed +at, these are stored in Fl_Widget::ix(), iy(), iw(), and ih(). + +<p>Resize should be declared public. + +<a name=destructor> +<h2>virtual Fl_Widget::~Fl_Widget();</h2> + +We all know why the destructor must be virtual don't we? Don't forget +to make it public. + +<a name=composite> +<h2>Making a Composite/Group Widget</h2> + +A "composite" widget contains one or more "child" widgets. To do this +you should subclass <a href=Fl_Group.html>Fl_Group</a> (it is +possible to make a composite object that is not a subclass of +Fl_Group, but this is very difficult). + +<p>Instances of the child widgets may be included in the parent: + +<ul><pre>class MyClass : public Fl_Group { + Fl_Button the_button; + Fl_Slider the_slider; + ... +}; +</pre></ul> + +<p>The constructor has to initialize these instances. They are +automatically add()ed to the group, since the Fl_Group constructor +does begin(). <i>Don't forget to call end():</i> + +<ul><pre>MyClass::MyClass(int x,int y,int w,int h) : + Fl_Group(x,y,w,h), + the_button(x+5,y+5,100,20), + the_slider(x,y+50,w,20) +{ + ...(you could add dynamically created child widgets here)... + end(); // don't forget to do this! +} +</pre></ul> + +<p>The child widgets need callbacks. These will be called with a +pointer to the children, but the widget itself may be found in the +parent() pointer of the child. Usually these callbacks can be static +private methods, with a matching private method: + +<ul><pre>void MyClass::slider_cb(Fl_Widget* v, void *) { // static method + ((MyClass*)(v->parent())->slider_cb(); +} +void MyClass::slider_cb() { // normal method + use(the_slider->value()); +} +</pre></ul> + +<p>If you make the handle() method, you can quickly pass all the +events to the children (notice that you don't need to override +handle() if your composite widget does nothing other than pass events +to the children): + +<ul><pre>int MyClass::handle(int event) { + if (Fl_Group::handle(event)) return 1; + ... handle events that children don't want ... +} +</pre></ul> + +<p>If you override draw() you need to draw all the children. If +redraw() or damage() is called on a child, damage(1) is done to the +group. Thus the 1 bit of damage() can be used to indicate that a +child needs to be drawn. It is fastest if you avoid drawing anything +else in this case: + +<ul><pre>int MyClass::draw() { + Fl_Widget*const* a = array(); + if (damage()==1) { // only redraw some children + for (int i=children(); i--; a++) update_child(**a); + } else { // total redraw + ... draw background graphics ... + // now draw all the children atop the background: + for (int i=children_; i--; a++) { + draw_child(**a); + draw_outside_label(**a); // you may not want to do this + } + } +} +</pre></ul> + +<p>Fl_Group provides some protected methods to make drawing easier: + +</ul><h4><code>void Fl_Group::draw_outside_label(Fl_Widget&) const;</code></h4><ul> + +Draw the labels that are <i>not</i> drawn by <a +href=#draw_label>draw_label()</a>. If you want more control over the +label positions you might want to call child->draw_label(x,y,w,h,a). + +</ul><h4><code>void Fl_Group::draw_child(Fl_Widget&);</code></h4><ul> + +This will force the child's damage() bits all to one and call draw() +on it, then clear the damage(). You should call this on all children +if a total redraw of your widget is requested, or if you draw +something (like a background box) that damages the child. Nothing is +done if the child is not visible() or if it is clipped. + +</ul><h4><code>void Fl_Group::update_child(Fl_Widget&);</code></h4><ul> + +Draws the child only if it's damage() is non-zero. You should call +this on all the children if your own damage is equal to 1. Nothing is +done if the child is not visible() or if it is clipped. + +</ul> + +<a name=window> +<h2>Making a subclass of Fl_Window</h2> + +<p>You may want your widget to be a subclass of Fl_Window. This can +be useful if your widget wants to occupy an entire window, and can +also be used to take advantage of system-provided clipping, or to work +with a library that expects a system window id to indicate where to +draw. + +<p>Subclassing Fl_Window is almost exactly like subclassing Fl_Widget, +in fact you can easily switch a subclass back and forth. Watch out +for the following differences: + +<ol> + +<li>Fl_Window is a subclass of Fl_Group so <i>make sure your constructor +calls end()</i> (unless you actually want children added to your +window). + +<li>When handling events and drawing, the lower-left corner is at 0,0, +not x(),y() as in other Fl_Widgets. For instance, to draw a box +around the widget, call draw_box(0,0,w(),h()), rather than +draw_box(x(),y(),w(),h()). + + +</ol> + +<p>You may also want to subclass Fl_Window in order to get access to +different X visuals or to change other X attributes of the windows, +<a href=x.html#window>See here for details</a>. + +<p><a href = index.html>(back to contents)</a> diff --git a/documentation/symbols.gif b/documentation/symbols.gif Binary files differnew file mode 100644 index 000000000..d4c1b8560 --- /dev/null +++ b/documentation/symbols.gif diff --git a/documentation/tabs.gif b/documentation/tabs.gif Binary files differnew file mode 100644 index 000000000..c1f151644 --- /dev/null +++ b/documentation/tabs.gif diff --git a/documentation/text.gif b/documentation/text.gif Binary files differnew file mode 100644 index 000000000..c96bcbf97 --- /dev/null +++ b/documentation/text.gif diff --git a/documentation/valuators.gif b/documentation/valuators.gif Binary files differnew file mode 100644 index 000000000..7dd1fbe75 --- /dev/null +++ b/documentation/valuators.gif diff --git a/documentation/value_slider.gif b/documentation/value_slider.gif Binary files differnew file mode 100644 index 000000000..668bd79fc --- /dev/null +++ b/documentation/value_slider.gif diff --git a/documentation/widgets.html b/documentation/widgets.html new file mode 100644 index 000000000..c85824acd --- /dev/null +++ b/documentation/widgets.html @@ -0,0 +1,6 @@ +<HTML> +<BODY> +<H1 ALIGN=RIGHT>A - Widget Reference</H1> +</BODY> +</HTML> + |
