diff options
| author | Michael R Sweet <michael.r.sweet@gmail.com> | 2001-11-29 19:24:00 +0000 |
|---|---|---|
| committer | Michael R Sweet <michael.r.sweet@gmail.com> | 2001-11-29 19:24:00 +0000 |
| commit | 09daf20b81cdae78772f07c0af22a571d7cc73eb (patch) | |
| tree | 1641f788cafe20b505355b0479ba0d528297eb30 /documentation | |
| parent | b105ab8b7fb6281635076559aae96f2b3b12fc51 (diff) | |
Documentation updates galore (up to chapter 7, still need to do chapter
8 and 9, tweek the appendices, and recapture the screenshots...)
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@1786 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
Diffstat (limited to 'documentation')
72 files changed, 3980 insertions, 3521 deletions
diff --git a/documentation/Fl.html b/documentation/Fl.html index 8ca85427f..21257a8c4 100644 --- a/documentation/Fl.html +++ b/documentation/Fl.html @@ -361,8 +361,31 @@ FLTK). <H4><A NAME="Fl.compose">int compose(int &del);</A></H4> +<p>Use of this function is very simple. Any text editing widget should +call this for each <tt>FL_KEYBOARD</tt> event. + +<p>If <i>true</i> is returned, then it has modified the +Fl::event_text() and Fl::event_length() to a set of <i>bytes</i> to +insert (it may be of zero length!). In will also set the "del" +parameter to the number of <i>bytes</i> to the left of the cursor to +delete, this is used to delete the results of the previous call to +Fl::compose(). + +<p>If <i>false</i> is returned, the keys should be treated as function +keys, and del is set to zero. You could insert the text anyways, if +you don't know what else to do. + +<p>Though the current implementation returns immediately, future +versions may take quite awhile, as they may pop up a window or do +other user-interface things to allow characters to be selected. + <H4><A NAME="Fl.compose_reset">void compose_reset();</A></H4> +<p>If the user moves the cursor, be sure to call Fl::compose_reset(). +The next call to Fl::compose() will start out in an initial state. In +particular it will not set "del" to non-zero. This call is very fast +so it is ok to call it many times and in many places. + <H4><A NAME="Fl.damage">int damage();<BR> void damage(int x);</A></H4> @@ -597,7 +620,7 @@ between this and <tt>FL_WHITE</tt>. <H4><A NAME="Fl.free_color">void free_color(Fl_Color c, int overlay = 0);</A></H4> -<P>Frees the specified color from the colormap, if applicable. +<P>Frees the specified color from the colormap, if applicable. If <tt>overlay</tt> is non-zero then the color is freed from the overlay colormap. diff --git a/documentation/Fl_Adjuster.html b/documentation/Fl_Adjuster.html index 70cade0b7..536590a5e 100644 --- a/documentation/Fl_Adjuster.html +++ b/documentation/Fl_Adjuster.html @@ -17,7 +17,7 @@ </PRE> </UL> <H3>Description</H3> -The <TT>Fl_Adjuster</TT> widget was stolen from Prisms, and has proven +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. <P ALIGN=CENTER><IMG SRC="adjuster1.gif" ALT="Fl_Adjuster widget."></P> <P>When you press a button and drag to the right the value increases. @@ -25,25 +25,25 @@ 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. +click decrements by 10 times the amount. <H3>Methods</H3> <UL> <LI><A href=#Fl_Adjuster.Fl_Adjuster>Fl_Adjuster</A></LI> <LI><A href=#Fl_Adjuster.~Fl_Adjuster>~Fl_Adjuster</A></LI> <LI><A href=#Fl_Adjuster.soft>soft</A></LI> </UL> -<H4><A name=Fl_Adjuster.Fl_Adjuster>Fl_Adjuster::Fl_Adjuster(int x, int +<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. + 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. + 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 + 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 index 01ed1b4c0..e575fad8a 100644 --- a/documentation/Fl_Box.html +++ b/documentation/Fl_Box.html @@ -17,23 +17,23 @@ </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. + 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> <LI><A href=#Fl_Box.~Fl_Box>~Fl_Box</A></LI> </UL> -<H4><A name=Fl_Box.Fl_Box>Fl_Box::Fl_Box(int x, int y, int w, int h, +<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 +<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 + 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.html#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 + 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. </P> <H4><A name=Fl_Box.~Fl_Box>Fl_Box::~Fl_Box(void)</A></H4> The destructor removes the box. diff --git a/documentation/Fl_Browser.html b/documentation/Fl_Browser.html index 22541b057..96a6ef5a7 100644 --- a/documentation/Fl_Browser.html +++ b/documentation/Fl_Browser.html @@ -19,32 +19,32 @@ </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 + 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> <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 + pointer can be used by the callbacks to reference the object the text describes. </P> -<P>The base class does nothing when the user clicks on it. The +<P>The base class does nothing when the user clicks on it. The subclasses <A href=Fl_Select_Browser.html#Fl_Select_Browser><TT> Fl_Select_Browser</TT></A>, <A href=Fl_Hold_Browser.html#Fl_Hold_Browser> <TT>Fl_Hold_Browser</TT></A>, and <A href=Fl_Multi_Browser.html#Fl_Multi_Browser> -<TT>Fl_Multi_Browser</TT></A> react to user clicks to select lines in +<TT>Fl_Multi_Browser</TT></A> react to user clicks to select lines in the browser and do callbacks. </P> <P>The base class called <A href=Fl_Browser_.html#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 +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 + 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>. </P> <H3>Methods</H3> <CENTER> @@ -88,51 +88,51 @@ subclass of <TT>Fl_Browser_</TT>. </P> </TD></TR> </TABLE> </CENTER> -<H4><A name=Fl_Browser.Fl_Browser>Fl_Browser::Fl_Browser(int, int, int, +<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. + 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 * = + 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 + 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. + of the new item. <H4><A name=Fl_Browser.bottomline>void Fl_Browser::bottomline(int n)</A></H4> Scrolls the browser so the bottom line in the browser is <TT>n</TT>. <H4><A name=Fl_Browser.clear>void Fl_Browser::clear()</A></H4> - Remove all the lines in the browser. + 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 + 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>. </P> -<H4><A name=Fl_Browser.column_widths>const int +<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 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 +. 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. </P> <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>. + 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>. </P> <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: + 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> <LI><CODE>@@</CODE> Print rest of line starting with '@' </LI> @@ -145,7 +145,7 @@ line is printed: font (sets font to FL_COURIER) </LI> <LI><CODE>@c</CODE> Center the line horizontally </LI> <LI><CODE>@r</CODE> Right-justify the text </LI> -<LI><CODE>@B0, @B1, ... @B255</CODE> Fill the backgound with +<LI><CODE>@B0, @B1, ... @B255</CODE> Fill the backgound with fl_color(n) </LI> <LI><CODE>@C0, @C1, ... @C255</CODE> Use fl_color(n) to draw the text </LI> <LI><CODE>@F0, @F1, ... </CODE> Use fl_font(n) to draw the text </LI> @@ -153,54 +153,54 @@ fl_color(n) </LI> <LI><CODE>@u</CODE> or <CODE>@_</CODE> Underline the text. </LI> <LI><CODE>@-</CODE> draw an engraved line through the middle. </LI> </UL> - Notice that the <CODE>@.</CODE> command can be used to reliably + 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 +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. </P> <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 + 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. +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 + 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>. + is set to the system error. The <TT>data()</TT> of each line is set +to <TT>NULL</TT>. <H4><A name=Fl_Browser.middleline>void Fl_Browser::middleline(int n)</A></H4> Scrolls the browser so the middle line in the browser is <TT>n</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. + 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. + 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. <P>The second form sets the vertical scrollbar position to <TT>p</TT>. </P> <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. + 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. + 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. + 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>. + 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>. </P> <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. +The first form returns the current top line in the browser. If there +is no vertical scrollbar then this will always return 1. <P>The second form scrolls the browser so the top line in the browser is <TT>n</TT>.</P> <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 index f7908f0f5..69c415fd2 100644 --- a/documentation/Fl_Browser_.html +++ b/documentation/Fl_Browser_.html @@ -19,18 +19,18 @@ </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 + 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 +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> -<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 +<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. </P> <H3>Methods</H3> <CENTER> @@ -95,15 +95,15 @@ other slow operation. </P> </TABLE> </CENTER> -<H4><A name="Fl_Browser_.Fl_Browser_">Fl_Browser::Fl_Browser(int, int, +<H4><A name="Fl_Browser_.Fl_Browser_">Fl_Browser::Fl_Browser(int, int, int, int, const char * = 0)</A></H4> -<P>The constructor makes an empty browser. +<P>The constructor makes an empty browser. <H4><A name="Fl_Browser_.~Fl_Browser_">Fl_Browser::~Fl_Browser(void)</A></H4> -<P>The destructor deletes all list items and destroys the browser. +<P>The destructor deletes all list items and destroys the browser. <H4><A NAME="Fl_Browser_.bbox">Fl_Browser_::bbox(int &x, int &y, int &w, int &h) const</A></H4> @@ -176,12 +176,12 @@ width from the item widths. <P>The second form handles an event within the specified bounding box. -<H4><A name="Fl_Browser_.has_scrollbar">void +<H4><A name="Fl_Browser_.has_scrollbar">void Fl_Browser_::has_scrollbar(int h)</A></H4> -<P>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>: +<P>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> @@ -196,10 +196,10 @@ this based on the value of <TT>h</TT>: <LI><CODE>Fl_Browser_::BOTH</CODE> - The default is both scrollbars. - <LI><CODE>Fl_Browser_::HORIZONTAL_ALWAYS</CODE> - Horizontal + <LI><CODE>Fl_Browser_::HORIZONTAL_ALWAYS</CODE> - Horizontal scrollbar always on, vertical always off. - <LI><CODE>Fl_Browser_::VERTICAL_ALWAYS</CODE> - Vertical + <LI><CODE>Fl_Browser_::VERTICAL_ALWAYS</CODE> - Vertical scrollbar always on, horizontal always off. <LI><CODE>Fl_Browser_::BOTH_ALWAYS</CODE> - Both always on. @@ -368,8 +368,8 @@ selected. <H4><A name="Fl_Browser_.textcolor">Fl_Color Fl_Browser_::textcolor() const <BR>void Fl_Browser_::textcolor(Fl_Color color)</A></H4> -<P>The first form gets the default text color for the lines in the -browser. +<P>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></P> @@ -377,8 +377,8 @@ browser. <H4><A name="Fl_Browser_.textfont">Fl_Font Fl_Browser_::textfont() const <BR>void Fl_Browser_::textfont(Fl_Font font)</A></H4> -<P>The first form gets the default text font for the lines in the -browser. +<P>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></P> @@ -386,8 +386,8 @@ browser. <H4><A name="Fl_Browser_.textsize">uchar Fl_Browser_::textsize() const <BR>void Fl_Browser_::textsize(uchar size)</A></H4> -<P>The first form gets the default text size for the lines in the -browser. +<P>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></P> diff --git a/documentation/Fl_Button.html b/documentation/Fl_Button.html index 26202efcb..921c86391 100644 --- a/documentation/Fl_Button.html +++ b/documentation/Fl_Button.html @@ -20,14 +20,14 @@ </PRE> </UL> <H3>Description</H3> -<P>Buttons generate callbacks when they are clicked by the user. You +<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> <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 +<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. </P> @@ -62,69 +62,69 @@ FL_KEYBOARD</TT> event. </P> </TD></TR> </TABLE> </CENTER> -<H4><A name=Fl_Button.Fl_Button>Fl_Button::Fl_Button(int x, int y, int +<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. + 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. + The destructor removed the button. <H4><A name=Fl_Button.clear>int Fl_Button::clear()</A></H4> - Same as <TT>value(0)</TT>. + 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 +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> . </P> <H4><A name=Fl_Button.set>int Fl_Button::set()</A></H4> - Same as <TT>value(1)</TT>. + 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). + 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 + 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 +, <CODE>FL_ALT | (FL_F + 10)</CODE>, or just <CODE>'a'</CODE>. A value of 0 disables the shortcut. </P> <P>The key can be any value returned by <A href=functions.html#event_key> -<TT>Fl::event_key()</TT></A>, but will usually be an ASCII letter. Use +<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> <P>The shift flags can be any set of values accepted by <A href=events.html#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" +<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). </P> <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: + 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> <LI><CODE>FL_TOGGLE_BUTTON</CODE>: The value is inverted. </LI> -<LI><CODE>FL_RADIO_BUTTON</CODE>: The value is set to 1, and all other +<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. </LI> </UL> - The second form sets the button type to <TT>t</TT>. + 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. + 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>: + 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 +<LI><CODE>0</CODE>: The callback is not done, instead changed() is turned on. </LI> -<LI><CODE>FL_WHEN_RELEASE</CODE>: The callback is done after the user +<LI><CODE>FL_WHEN_RELEASE</CODE>: The callback is done after the user successfully clicks the button, or when a shortcut is typed. </LI> -<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 +<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). </LI> </UL> </BODY></HTML> diff --git a/documentation/Fl_Chart.html b/documentation/Fl_Chart.html index 7a65a772d..cc00cce70 100644 --- a/documentation/Fl_Chart.html +++ b/documentation/Fl_Chart.html @@ -51,69 +51,69 @@ This widget displays simple charts and is provided for Forms compatibility. </TD></TR> </TABLE> </CENTER> -<H4><A name=Fl_Chart.Fl_Chart>Fl_Chart::Fl_Chart(int x, int y, int w, +<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>. + 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 = + 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. +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 + 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>. </P> <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. + 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 + 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. +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 +The <TT>maxsize</TT> method gets or sets the maximum number of data values for a chart. If you do not call this method then the chart will be allowed to grow to any size depending on available memory. -<H4><A name=Fl_Chart.replace>void replace(int pos, double value, const +<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. +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. + 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: + 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 +<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 +<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 +<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>. + The second form of <TT>type()</TT> sets the chart type to <TT>t</TT>. </BODY></HTML> diff --git a/documentation/Fl_Check_Button.html b/documentation/Fl_Check_Button.html index d1074e2ac..0b6a88e99 100644 --- a/documentation/Fl_Check_Button.html +++ b/documentation/Fl_Check_Button.html @@ -17,14 +17,14 @@ </PRE> </UL> <H3>Description</H3> -Buttons generate callbacks when they are clicked by the user. You +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 ALIGN=CENTER><IMG SRC="Fl_Check_Button.gif" ALT="Fl_Check_Button widget"></P> -<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 +<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.</P> <H3>Methods</H3> <UL> @@ -32,10 +32,10 @@ defaults to FL_RED.</P> <LI><A href=#Fl_Check_Button.~Fl_Check_Button>~Fl_Check_Button</A></LI> </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 +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. + 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 index ad22c3448..266c217d5 100644 --- a/documentation/Fl_Choice.html +++ b/documentation/Fl_Choice.html @@ -17,26 +17,26 @@ </PRE> </UL> <H3>Description</H3> - This is a button that when pushed pops up a menu (or hierarchy of + 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.html#Fl_Menu_Item><TT> -Fl_Menu_Item</TT></A> objects. Motif calls this an OptionButton. +Fl_Menu_Item</TT></A> objects. Motif calls this an OptionButton. <P>The only difference between this and a <A href=Fl_Menu_Button.html#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 +<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> -<P>When the user picks an item off the menu the <TT>value()</TT> is set +<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> -<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. +<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> -<P>The menu will also pop up in response to shortcuts indicated by +<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.html#Fl_Button> <TT>Fl_Button</TT></A> for a description of this. </P> -<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 +<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. </P> <P ALIGN=CENTER><IMG src="choice.gif" ALT="Fl_Choice widget."></P> <H3>Methods</H3> @@ -49,33 +49,33 @@ item names are only looked at when the menu is popped up, however. </P> <LI><A href=#Fl_Choice.set_changed>set_changed</A></LI> <LI><A href=#Fl_Choice.value>value</A></LI> </UL> -<H4><A name=Fl_Choice.Fl_Choice>Fl_Choice::Fl_Choice(int x, int y, int +<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>. + 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_.html#Fl_Menu_> <TT>Fl_Menu_</TT></A> for the methods to set or change the menu. </P> <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. + 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>. + 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 + 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. + 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. + 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 + 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 index 5f217bb31..682b06414 100644 --- a/documentation/Fl_Clock.html +++ b/documentation/Fl_Clock.html @@ -17,9 +17,9 @@ </PRE> </UL> <H3>Description</H3> - This widget provides a round analog clock display and is provided for + This widget provides a round analog clock display and is provided for Forms compatibility. It installs a 1-second timeout callback using <A href=functions.html#add_timeout> -<TT>Fl::add_timeout()</TT></A>. +<TT>Fl::add_timeout()</TT></A>. <P ALIGN=CENTER><IMG src="clock.gif" ALT="Fl_Clock widget."> <IMG src="round_clock.gif" ALT="Fl_Clock widget."></P> <H3>Methods</H3> <UL> @@ -30,28 +30,28 @@ Forms compatibility. It installs a 1-second timeout callback using <A href=func <LI><A href=#Fl_Clock.second>second</A></LI> <LI><A href=#Fl_Clock.value>value</A></LI> </UL> -<H4><A name=Fl_Clock.Fl_Clock>Fl_Clock::Fl_Clock(int x, int y, int w, +<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>. + 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 + 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. +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). + 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). + 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). + 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 + 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). </P> </BODY></HTML> diff --git a/documentation/Fl_Color_Chooser.html b/documentation/Fl_Color_Chooser.html index 89fc52592..e5761915b 100644 --- a/documentation/Fl_Color_Chooser.html +++ b/documentation/Fl_Color_Chooser.html @@ -17,14 +17,14 @@ </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. + 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> @@ -41,47 +41,47 @@ or value is zero. <LI><A href=#Fl_Color_Chooser.value>value</A></LI> </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 +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 + 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. + 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, + 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 +<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() + 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. + 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. + 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. + 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, + 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 + 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&, + 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&, + 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 index 34fffb768..6b2428050 100644 --- a/documentation/Fl_Counter.html +++ b/documentation/Fl_Counter.html @@ -17,8 +17,8 @@ </PRE> </UL> <H3>Description</H3> - The <TT>Fl_Counter</TT> widget is provided for forms compatibility. - It controls a single floating point value. + The <TT>Fl_Counter</TT> widget is provided for forms compatibility. + It controls a single floating point value. <P ALIGN=CENTER><IMG src="counter.gif" ALT="Fl_Counter widget."></P> <H3>Methods</H3> <UL> @@ -27,21 +27,21 @@ <LI><A href=#Fl_Counter.lstep>lstep</A></LI> <LI><A href=#Fl_Counter.type>type</A></LI> </UL> -<H4><A name=Fl_Counter.Fl_Counter>Fl_Counter::Fl_Counter(int x, int y, +<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>. + 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. +Destroys the valuator. <H4><A name=Fl_Counter.lstep>double Fl_Counter::lstep() const</A></H4> -Set the increment for the double-arrow buttons. The default -value is 1.0. +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: + Sets the type of counter: <UL> -<LI><TT>FL_NORMAL_COUNTER</TT> - Displays a counter with 4 arrow +<LI><TT>FL_NORMAL_COUNTER</TT> - Displays a counter with 4 arrow buttons. </LI> -<LI><TT>FL_SIMPLE_COUNTER</TT> - Displays a counter with only 2 arrow +<LI><TT>FL_SIMPLE_COUNTER</TT> - Displays a counter with only 2 arrow buttons. </LI> </UL> </BODY></HTML> diff --git a/documentation/Fl_Dial.html b/documentation/Fl_Dial.html index 4184ddd99..c42df0c9e 100644 --- a/documentation/Fl_Dial.html +++ b/documentation/Fl_Dial.html @@ -17,8 +17,8 @@ </PRE> </UL> <H3>Description</H3> - The <TT>Fl_Dial</TT> widget provides a circular dial to control a -single floating point value. + The <TT>Fl_Dial</TT> widget provides a circular dial to control a +single floating point value. <P ALIGN=CENTER><IMG src="dial.gif" ALT="Fl_Dial widget."></P> <H3>Methods</H3> <UL> @@ -29,12 +29,12 @@ single floating point value. <LI><A href=#Fl_Dial.angles>angles</A></LI> <LI><A href=#Fl_Dial.type>type</A></LI> </UL> -<H4><A name=Fl_Dial.Fl_Dial>Fl_Dial::Fl_Dial(int x, int y, int w, int +<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>. + 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. + Destroys the valuator. <H4> <A name=Fl_Dial.angles> @@ -52,7 +52,7 @@ progress clockwise). Normally angle1 is less than angle2, but if you reverse them the dial moves counter-clockwise. <H4><A name=Fl_Dial.type>type(uchar)</A></H4> - Sets the type of the dial to: + Sets the type of the dial to: <UL> <LI><TT>FL_NORMAL_DIAL</TT> - Draws a normal dial with a knob. </LI> <LI><TT>FL_LINE_DIAL</TT> - Draws a dial with a line. </LI> diff --git a/documentation/Fl_Double_Window.html b/documentation/Fl_Double_Window.html index 7be7b758d..25161e516 100644 --- a/documentation/Fl_Double_Window.html +++ b/documentation/Fl_Double_Window.html @@ -17,19 +17,19 @@ </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 + 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: </P> <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. + 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> @@ -37,15 +37,15 @@ does not exist for every visual. <LI><A href=#Fl_Double_Window.pixmap>pixmap</A></LI> </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 +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 + 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. + 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 diff --git a/documentation/Fl_Float_Input.html b/documentation/Fl_Float_Input.html index a19dda0dd..42a03f15f 100644 --- a/documentation/Fl_Float_Input.html +++ b/documentation/Fl_Float_Input.html @@ -26,10 +26,10 @@ <LI><A href=#Fl_Float_Input.~Fl_Float_Input>~Fl_Float_Input</A></LI> </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 +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 + 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 index 89a8de00f..aa7046e80 100644 --- a/documentation/Fl_Free.html +++ b/documentation/Fl_Free.html @@ -17,11 +17,11 @@ </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 + 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: </P> <UL> <PRE> @@ -32,19 +32,19 @@ function is called: </P> #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. +<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. </P> <H3>Methods</H3> <UL> <LI><A href=#Fl_Free.Fl_Free>Fl_Free</A></LI> <LI><A href=#Fl_Free.~Fl_Free>~Fl_Free</A></LI> </UL> -<H4><A name=Fl_Free.Fl_Free>Fl_Free(uchar type, int, int, int, int, +<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: + function. The handle function should be declared as follows: <UL> <PRE> int @@ -55,9 +55,9 @@ handle_function(Fl_Widget *w, 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: + 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: diff --git a/documentation/Fl_Gl_Window.html b/documentation/Fl_Gl_Window.html index 21276d2e0..fd5957e57 100644 --- a/documentation/Fl_Gl_Window.html +++ b/documentation/Fl_Gl_Window.html @@ -17,15 +17,15 @@ </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 + 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. Fl_Gl_Window 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 + 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. </P> <H3>Methods</H3> <CENTER> @@ -64,32 +64,32 @@ very well for single-buffered. </P> </TD></TR> </TABLE> </CENTER> -<H4><A name=Fl_Gl_Window.Fl_Gl_Window>Fl_Gl_Window::Fl_Gl_Window(int x, +<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 + 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. + 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 +<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 +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 +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> -<P>If double-buffering is enabled in the window, the back and front +<P>If double-buffering is enabled in the window, the back and front buffers are swapped after this function is completed. </P> <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: + 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> <LI><TT>FL_RGB8</TT> - RGB color with at least 8 bits of each color </LI> @@ -102,22 +102,22 @@ any of the following OR'd together: <LI><TT>FL_STENCIL</TT> - stencil buffer </LI> <LI><TT>FL_MULTISAMPLE</TT> - multisample antialiasing </LI> </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>. +<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> -<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 +<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 + 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! </P> <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. + Returns non-zero if the hardware supports the given or current OpenGL +mode. <h4><a name=Fl_Gl_Window.context>void* Fl_Gl_Window::context() const; <br>void Fl_Gl_Window::context(void*, int destroy_flag = false);</a></h4> @@ -136,11 +136,11 @@ href=#Fl_Gl_Window.mode><tt>mode()</tt></a> is changed, or the next time <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 +<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: +draw()</TT> method to avoid unneccessarily initializing the OpenGL +context. Just do this: <UL><PRE> void mywindow::draw() { if (!valid()) { @@ -153,59 +153,59 @@ void mywindow::draw() { } </PRE></UL> -You can turn <TT>valid()</TT> on by calling <TT>valid(1)</TT>. You +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. +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>. + 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 + 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. +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 + 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 + 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 +draw_overlay()</TT> method being called and can also be used to implement feedback and/or selection within the <TT>handle()</TT> - method. + 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. + 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 + 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 + 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 + 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 + 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. +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 +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. </P> </BODY></HTML> diff --git a/documentation/Fl_Group.html b/documentation/Fl_Group.html index 1e8e4dac6..957b4bf3f 100644 --- a/documentation/Fl_Group.html +++ b/documentation/Fl_Group.html @@ -19,12 +19,12 @@ </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 + 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.html#Fl_Window><TT>Fl_Window</TT></A>, however -groups can also be used to control radio buttons or to enforce resize -behavior. + is <A href=Fl_Window.html#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% summary="Fl_Group methods."> @@ -61,17 +61,17 @@ behavior. </TD></TR> </TABLE> </CENTER> -<H4><A name=Fl_Group.Fl_Group>Fl_Group::Fl_Group(int x, int y, int w, +<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>. + 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 + 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. +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> @@ -99,8 +99,8 @@ This does <tt>insert(w, find(beforethis))</tt>. This will append the widget if <tt>beforethis</tt> is not in the group. <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. +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.current>static Fl_Group *Fl_Group::current() <BR> static void Fl_Group::current(Fl_Group *w)</A></H4> @@ -108,48 +108,48 @@ not currently a child of this group. constructor automatically does <tt>current()->add(widget)</tt> if this is not null. To prevent new widgets from being added to a group, call <TT>Fl_Group::current(0)</TT>. <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> <i>is exactly the same as</i> <TT>current(this)</TT>. +<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> <i>is exactly the same as</i> <TT>current(this)</TT>. <P><I>Don't forget to <TT>end()</TT> the group or window!</I></P> <H4><A name=Fl_Group.end>void Fl_Group::end()</A></H4> -<TT>end()</TT> <i>is exactly the same as</i> <TT>current(this->parent())</TT>. Any new widgets -added to the widget tree will be added to the parent of the group. +<TT>end()</TT> <i>is exactly the same as</i> <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.array>const Fl_Widget **Fl_Group::array() const</A></H4> Returns a pointer to the array of children. <I>This pointer is only valid until the next time a child is added or removed.</I> <H4><A name=Fl_Group.child>Fl_Widget *Fl_Group::child(int n) const</A></H4> Returns <tt>array()[n]</tt>. <i>No range checking is done!</i> <H4><A name=Fl_Group.children>int Fl_Group::children() const</A></H4> - Returns how many child widgets the group has. + Returns how many child widgets the group has. <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. +NULL</TT> or not found. <H4><A name=Fl_Group.resizable>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. + 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> <P align=center><IMG align=TOP SRC="resizebox1.gif" ALT="Resizeable groups"> <IMG align=TOP SRC="resizebox2.gif" ALT="Resizeable groups"></P> -<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 +<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> -<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 +<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. </P> -<H4><A name=Fl_Group.add_resizable>Fl_Group +<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. + Adds a widget to the group and makes it the resizable widget. </BODY></HTML> diff --git a/documentation/Fl_Hold_Browser.html b/documentation/Fl_Hold_Browser.html index 3cd7ba673..da9adf5ac 100644 --- a/documentation/Fl_Hold_Browser.html +++ b/documentation/Fl_Hold_Browser.html @@ -18,12 +18,12 @@ </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.html#Fl_Browser><TT>Fl_Browser</TT></A> for + 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.html#Fl_Browser><TT>Fl_Browser</TT></A> for methods to add and remove lines from the browser. </P> <H3>Methods</H3> <UL> @@ -34,22 +34,22 @@ methods to add and remove lines from the browser. </P> <LI><A href=#Fl_Hold_Browser.value>value</A></LI> </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 +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 + 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 +. +<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>. + 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>. + 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.html#Fl_Multi_Browser> -<TT>Fl_Multi_Browser</TT></A>. If you turn on the selection of more -than one line the results are unpredictable. +<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 + 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 index a99da8d93..5474d5e37 100644 --- a/documentation/Fl_Input.html +++ b/documentation/Fl_Input.html @@ -20,13 +20,13 @@ </PRE> </UL> <H3>Description</H3> -<P>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 assumes the font can draw any characters in the -ISO-8859-1 character set. +<P>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 assumes the font can draw any characters in the +ISO-8859-1 character set. <CENTER><TABLE border=1 WIDTH=90% summary="Fl_Input keyboard and mouse bindings."> @@ -43,32 +43,32 @@ clipboard by selecting the region with mouse button 2. <TR><TD><B>Mouse button 3</B></TD><TD>Currently acts like button 1.</TD></TR> -<TR><TD><B>Backspace</B></TD><TD>Deletes one character to the left, or +<TR><TD><B>Backspace</B></TD><TD>Deletes one character to the left, or deletes the selected region.</TD></TR> <TR><TD><B>Enter</B></TD><TD>May cause the callback, see when().</TD></TR> <TR><TD><B>^A or Home</B></TD><TD>Go to start of line.</TD></TR> <TR><TD><B>^B or Left</B></TD><TD>Move left</TD></TR> <TR><TD><B>^C</B></TD><TD>Copy the selection to the clipboard</TD></TR> -<TR><TD><B>^D or Delete</B></TD><TD>Deletes one character to the right +<TR><TD><B>^D or Delete</B></TD><TD>Deletes one character to the right or deletes the selected region.</TD></TR> <TR><TD><B>^E or End</B></TD><TD>Go to the end of line.</TD></TR> <TR><TD><B>^F or Right</B></TD><TD>Move right</TD></TR> -<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 +<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> -<TR><TD><B>^N or Down</B></TD><TD>Move down (for Fl_Multiline_Input +<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> -<TR><TD><B>^P or Up</B></TD><TD>Move up (for Fl_Multiline_Input only, +<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> <TR><TD><B>^U</B></TD><TD>Delete everything.</TD></TR> <TR><TD><B>^V or ^Y</B></TD><TD>Paste the clipboard</TD></TR> -<TR><TD><B>^X or ^W</B></TD><TD>Copy the region to the clipboard and +<TR><TD><B>^X or ^W</B></TD><TD>Copy the region to the clipboard and delete it.</TD></TR> -<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 +<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> -<TR><TD><B>Shift+move</B></TD><TD>Move the cursor but also extend the +<TR><TD><B>Shift+move</B></TD><TD>Move the cursor but also extend the selection.</TD></TR> <TR><TD><B>RightCtrl or @@ -259,76 +259,76 @@ inserted. </TD></TR> </TABLE> </CENTER> -<H4><A name=Fl_Input.Fl_Input>Fl_Input::Fl_Input(int x, int y, int w, +<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>. + 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. + 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 + 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 +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. </P> -<H4><A name=Fl_Input.static_value>int Fl_Input::static_value(const +<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. + 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. + 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. + 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>: + 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 +<LI><TT>0</TT>: The callback is not done, but <TT>changed()</TT> is turned on. </LI> -<LI><TT>FL_WHEN_CHANGED</TT>: The callback is done each time the text +<LI><TT>FL_WHEN_CHANGED</TT>: The callback is done each time the text is changed by the user. </LI> -<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 +<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> -<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 +<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> -<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 +<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. </LI> </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. + 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. + 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() + 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. diff --git a/documentation/Fl_Input_.html b/documentation/Fl_Input_.html index c2e4a617b..18790d0ea 100644 --- a/documentation/Fl_Input_.html +++ b/documentation/Fl_Input_.html @@ -21,9 +21,9 @@ <H3>Description</H3> This is a virtual base class below <A href=Fl_Input.html#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. +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: </P> <UL> @@ -73,78 +73,78 @@ type()</TT> to one of the following values: </P> </TD></TR> </TABLE> </CENTER> -<H4><A name=Fl_Input_.Fl_Input_>Fl_Input_::Fl_Input_(int x, int y, int +<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>. + 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) + 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) + 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. + 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 + 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 + 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 +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. + 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_.maximum_size">void Fl_Input_::maximum_size(int m)<BR> int Fl_Input_::maximum_size() const</A></H4> <P>Sets or returns the maximum length of the input field. <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 + 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>. </P> <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, + 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. +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> -<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 +<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> <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> -<P><TT>cut()</TT> and <TT>insert()</TT> are just inline functions that +<P><TT>cut()</TT> and <TT>insert()</TT> are just inline functions that call <TT>replace()</TT>. </P> <H4><A name=Fl_Input_.cut>int Fl_Input_::cut() <BR> int Fl_Input_::cut(int n) @@ -153,24 +153,24 @@ call <TT>replace()</TT>. </P> 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. + 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. </P> -<H4><A name=Fl_Input_.insert>int Fl_Input_::insert(const char *t,int +<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>. + 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. +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. + 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 + 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 index 81fe7069c..de4c9e3a0 100644 --- a/documentation/Fl_Int_Input.html +++ b/documentation/Fl_Int_Input.html @@ -25,10 +25,10 @@ <LI><A href=#Fl_Int_Input.Fl_Int_Input>Fl_Int_Input</A></LI> <LI><A href=#Fl_Int_Input.~Fl_Int_Input>~Fl_Int_Input</A></LI> </UL> -<H4><A name=Fl_Int_Input.Fl_Int_Input>Fl_Int_Input::Fl_Int_Input(int x, +<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 + 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 index c7598a7a2..a5e597ef3 100644 --- a/documentation/Fl_Light_Button.html +++ b/documentation/Fl_Light_Button.html @@ -17,14 +17,14 @@ </PRE> </UL> <H3>Description</H3> -Buttons generate callbacks when they are clicked by the user. You +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>. +and <TT>when()</TT>. <P ALIGN=CENTER><IMG SRC="Fl_Light_Button.gif" ALT="Fl_Light_Button widget."></P> -<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 +<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.</P> <H3>Methods</H3> <UL> @@ -32,10 +32,10 @@ FL_YELLOW.</P> <LI><A href=#Fl_Light_Button.~Fl_Light_Button>~Fl_Light_Button</A></LI> </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 +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. + 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 index ba6ad06dd..bc34198f6 100644 --- a/documentation/Fl_Menu_.html +++ b/documentation/Fl_Menu_.html @@ -19,11 +19,11 @@ </PRE> </UL> <H3>Description</H3> -All widgets that have a menu in FLTK are subclassed off of this class. +All widgets that have a menu in FLTK are subclassed off of this class. Currently FLTK provides you with <A href=Fl_Menu_Button.html#Fl_Menu_Button> <TT>Fl_Menu_Button</TT></A>, <A href=Fl_Menu_Bar.html#Fl_Menu_Bar><TT> Fl_Menu_Bar</TT></A>, and <A href=Fl_Choice.html#Fl_Choice><TT>Fl_Choice</TT> -</A>. +</A>. <P>The class contains a pointer to an array of structures of type <A href=Fl_Menu_Item.html#Fl_Menu_Item> <TT>Fl_Menu_Item</TT></A>. The @@ -71,7 +71,7 @@ be "private": a dynamically allocated array managed by the Fl_Menu_. </TABLE> </CENTER> -<H4><A name=Fl_Menu_.Fl_Menu_>Fl_Menu_::Fl_Menu_(int x, int y, int w, +<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, @@ -124,9 +124,9 @@ will result in a submenu called "foo" and one in that called copied to new memory and can be freed. The other arguments (including the shortcut) are copied into the menu item unchanged. </P> -<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 +<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> <P>The return value is the index into the array that the entry was put. </P> @@ -163,42 +163,42 @@ href=Fl_Menu_Item.html>Fl_Menu_Item</a>. <BR> int Fl_Menu_::value(int) <BR> const Fl_Menu_Item* mvalue() const <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. + 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* +<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. + 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 + 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=osissues.html#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 +<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 (so don't destroy the widget!)</P> <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>. + Returns the title of the last item chosen, or 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. + 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. + 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. + 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 + 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 index 3fc543899..840bbbd86 100644 --- a/documentation/Fl_Menu_Bar.html +++ b/documentation/Fl_Menu_Bar.html @@ -17,47 +17,47 @@ </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 + 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.html#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 + 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> <P ALIGN=CENTER><IMG src="menubar.gif" ALT="Fl_Menu_Bar widget."></P> -<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 +<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> -<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 +<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> -<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 +<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> -<P>Typing the <TT>shortcut()</TT> of any of the menu items will cause +<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. </P> <H3>Methods</H3> <UL> <LI><A href=#Fl_Menu_Bar.Fl_Menu_Bar>Fl_Menu_Bar</A></LI> <LI><A href=#Fl_Menu_Bar.~Fl_Menu_Bar>~Fl_Menu_Bar</A></LI> </UL> -<H4><A name=Fl_Menu_Bar.Fl_Menu_Bar>Fl_Menu_Bar::Fl_Menu_Bar(int x, int +<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>. + 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_.html#Fl_Menu_> <TT>Fl_Menu_</TT></A> for the methods to set or change the menu. </P> <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 + 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> -<P><TT>label()</TT> is ignored unless you change <TT>align()</TT> to +<P><TT>label()</TT> is ignored unless you change <TT>align()</TT> to put it outside the menubar. </P> <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 + 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 index b8e4a382d..602a50472 100644 --- a/documentation/Fl_Menu_Button.html +++ b/documentation/Fl_Menu_Button.html @@ -17,23 +17,23 @@ </PRE> </UL> <H3>Description</H3> - This is a button that when pushed pops up a menu (or hierarchy of + 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.html#Fl_Menu_Item><TT> -Fl_Menu_Item</TT></A> objects. +Fl_Menu_Item</TT></A> objects. <P ALIGN=CENTER><IMG src="menu_button.gif" ALT="Fl_Menu_Button widget."></P> -<P>Normally any mouse button will pop up a menu and it is lined up +<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> -<P>The menu will also pop up in response to shortcuts indicated by +<P>The menu will also pop up in response to shortcuts indicated by putting a '&' character in the <TT>label()</TT>. </P> -<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 +<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> -<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 +<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. </P> <H3>Methods</H3> <UL> @@ -43,37 +43,37 @@ instead. </P> <LI><A href=#Fl_Menu_Button.type>type</A></LI> </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 +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>. + 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_.html#Fl_Menu_> <TT>Fl_Menu_</TT></A> for the methods to set or change the menu. </P> -<H4><A name=Fl_Menu_Button.~Fl_Menu_Button>virtual +<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. + 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. + 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_Menu_Button::type(uchar)</A></H4> - If <TT>type()</TT> is zero a normal menu button is produced. If it is + 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, + 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 +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> -<P>The popup menus appear with the cursor pointing at the previously +<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 +value(0)</TT> after the menu items are picked to forget the current item. </P> </BODY></HTML> diff --git a/documentation/Fl_Menu_Item.html b/documentation/Fl_Menu_Item.html index bb8e495c1..582088f2e 100644 --- a/documentation/Fl_Menu_Item.html +++ b/documentation/Fl_Menu_Item.html @@ -47,7 +47,7 @@ enum { // values for flags: }; </PRE> </UL> -Typically menu items are statically defined; for example: +Typically menu items are statically defined; for example: <UL><PRE> Fl_Menu_Item popup[] = { {"&alpha", FL_ALT+'a', the_cb, (void*)1}, @@ -73,12 +73,12 @@ produces: 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 +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 +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. </P> <H3>Methods</H3> <CENTER> @@ -132,165 +132,165 @@ releases of FLTK. </P> <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 + 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 +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() + 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() + 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.html#Enumerations> -enumeration list</A> for predefined fonts. The default value is a +enumeration list</A> for predefined fonts. The default value is a Helvetica font. The function <A href=functions.html#set_font><TT> -Fl::set_font()</TT></A> can define new fonts. +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 + 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 + 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. +((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 + 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 + 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. +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 + 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. +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=functions.html#event_key> -<TT>Fl::event_key()</TT></A>, but will usually be an ASCII letter. Use +<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> <P>The shift flags can be any set of values accepted by <A href=functions.html#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" +<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). </P> <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 + 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. + 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. + 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. + 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. + 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 + 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. + 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. + 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. + 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. + 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. + 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. + 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. + 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. + 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 + 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 + 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 +<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> -<P><TT>title</TT> is a character string title for the menu. If +<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> <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 +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> <P><TT>button</TT> is a pointer to an <A href=Fl_Menu_.html#Fl_Menu_><TT> -Fl_Menu_</TT></A> from which the color and boxtypes for the menu are +Fl_Menu_</TT></A> from which the color and boxtypes for the menu are pulled. If <TT>NULL</TT> then defaults are used. </P> -<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, +<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 +<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 + 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_Bar</TT> widget. </P> -<H4><A name=Fl_Menu_Item.test_shortcut>const Fl_Menu_Item* +<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 ' + 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> Returns the number of Fl_Menu_Item structures that make up this menu, correctly counting submenus. This includes the "terminator" item at the end. So to copy a menu you need to copy <tt>size()*sizeof(Fl_Menu_Item)</tt> bytes. -<H4><A name=Fl_Menu_Item.next>const Fl_Menu_Item* +<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 + 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 index 9ca520209..266f45822 100644 --- a/documentation/Fl_Menu_Window.html +++ b/documentation/Fl_Menu_Window.html @@ -17,10 +17,10 @@ </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. + 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> @@ -29,17 +29,17 @@ redraw. <LI><A href=#Fl_Menu_Window.set_overlay>set_overlay</A></LI> </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 +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 + 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. + 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. + 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 index 350fb9ca4..49e691ba7 100644 --- a/documentation/Fl_Multi_Browser.html +++ b/documentation/Fl_Multi_Browser.html @@ -18,13 +18,13 @@ </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.html#Fl_Browser><TT>Fl_Browser</TT></A> for + 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.html#Fl_Browser><TT>Fl_Browser</TT></A> for methods to add and remove lines from the browser. </P> <H3>Methods</H3> <UL> @@ -35,22 +35,22 @@ methods to add and remove lines from the browser. </P> <LI><A href=#Fl_Multi_Browser.value>value</A></LI> </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 +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 + 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 +. +<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>. + 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. + 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. + 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 + 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 index dfec9c12d..dd8c4ab16 100644 --- a/documentation/Fl_Multiline_Input.html +++ b/documentation/Fl_Multiline_Input.html @@ -17,13 +17,13 @@ </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 + 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. </P> <H3>Methods</H3> <UL> @@ -33,11 +33,11 @@ of bloat. </P> </LI> </UL> <H4><A name=Fl_Multiline_Input.Fl_Multiline_Input> -Fl_Multiline_Input::Fl_Multiline_Input(int x, int y, int w, int h, +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 + 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 +. +<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 index aad161675..6c7a08616 100644 --- a/documentation/Fl_Multiline_Output.html +++ b/documentation/Fl_Multiline_Output.html @@ -17,9 +17,9 @@ </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. + 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> @@ -28,11 +28,11 @@ next column. ~Fl_Multiline_Output</A></LI> </UL> <H4><A name=Fl_Multiline_Output.Fl_Multiline_Output> -Fl_Multiline_Output::Fl_Multiline_Output(int x, int y, int w, int h, +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 + 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 +. +<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 index fee6d91b9..d8fec183b 100644 --- a/documentation/Fl_Output.html +++ b/documentation/Fl_Output.html @@ -20,18 +20,18 @@ </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. +, <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. <CENTER><IMG src="text.gif" ALT="Fl_Output widget."></CENTER> <P>There is a single subclass, <A href=Fl_Multiline_Output.html#Fl_Multiline_Output> -Fl_Multiline_Output</A>, which allows you to display multiple lines of +Fl_Multiline_Output</A>, which allows you to display multiple lines of text. </P> -<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 +<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. </P> <H3>Methods</H3> <UL> @@ -44,36 +44,36 @@ set. </P> <LI><A href=#Fl_Output.textsize>textsize</A></LI> <LI><A href=#Fl_Output.value>value</A></LI> </UL> -<H4><A name=Fl_Output.Fl_Output>Fl_Output::Fl_Output(int x, int y, int +<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>. + 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. + 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 + 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 +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. </P> <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. + 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. + 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. + 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. + 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 index 43401ec12..1a838196d 100644 --- a/documentation/Fl_Overlay_Window.html +++ b/documentation/Fl_Overlay_Window.html @@ -17,14 +17,14 @@ </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 + 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. </P> <H3>Methods</H3> <UL> @@ -34,23 +34,23 @@ overlay will blink if you change the image in the window. </P> <LI><A href=#Fl_Overlay_Window.redraw_overlay>redraw_overlay</A></LI> </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 +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 + 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.draw_overlay>virtual void + Destroys the window and all child widgets. +<H4><A name=Fl_Overlay_Window.draw_overlay>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 + 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.html#Drawing> -<FL/fl_draw.H></A>. +<FL/fl_draw.H></A>. <H4><A name=Fl_Overlay_Window.redraw_overlay>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 + 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 index a26e81e5c..ae1fd2477 100644 --- a/documentation/Fl_Pack.html +++ b/documentation/Fl_Pack.html @@ -17,15 +17,15 @@ </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 + 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 + 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> -<P>This widget is needed for the <A href=Fl_Tabs.html#Fl_Tabs><TT>Fl_Tabs</TT></A>. +<P>This widget is needed for the <A href=Fl_Tabs.html#Fl_Tabs><TT>Fl_Tabs</TT></A>. In addition you may want to put the <TT>Fl_Pack</TT> inside an <A href=Fl_Scroll.html#Fl_Scroll> <TT>Fl_Scroll</TT></A>. </P> <H3>Methods</H3> @@ -34,18 +34,18 @@ widgets. </P> <LI><A href=#Fl_Pack.~Fl_Pack>~Fl_Pack</A></LI> <LI><A href=#Fl_Pack.spacing>spacing</A></LI> </UL> -<H4><A name=Fl_Pack.Fl_Pack>Fl_Pack::Fl_Pack(int x, int y, int w, int +<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>. + 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 + 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. +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 + 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 index 2cf1f2727..f70d8cef1 100644 --- a/documentation/Fl_Positioner.html +++ b/documentation/Fl_Positioner.html @@ -17,10 +17,10 @@ </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>. + 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 ALIGN=CENTER><IMG src="positioner.gif" ALT="Fl_Positioner widget."></P> <H3>Methods</H3> <CENTER> @@ -41,29 +41,29 @@ crosshairs is <TT>selection_color()</TT>. </TABLE> </CENTER> <H4><A name=Fl_Positioner.Fl_Positioner> -Fl_Positioner::Fl_Positioner(int x, int y, int w, int h, const char +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 + 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, + 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>. + 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. + 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. + 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. + 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. + 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. + 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 index bea62f78c..fe94d54b0 100644 --- a/documentation/Fl_Repeat_Button.html +++ b/documentation/Fl_Repeat_Button.html @@ -14,21 +14,21 @@ <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. + 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> <LI><A href=#Fl_Repeat_Button.~Fl_Repeat_Button>~Fl_Repeat_Button</A></LI> </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 +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 + 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 +. +<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 index 1acc552de..6c11ae9c3 100644 --- a/documentation/Fl_Return_Button.html +++ b/documentation/Fl_Return_Button.html @@ -14,9 +14,9 @@ <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. +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. <P ALIGN=CENTER><IMG SRC="Fl_Return_Button.gif" ALT="Fl_Return_Button widget."></P> <H3>Methods</H3> <UL> @@ -24,11 +24,11 @@ Enter key. A carriage-return symbol is drawn next to the button label. <LI><A href=#Fl_Return_Button.~Fl_Return_Button>~Fl_Return_Button</A></LI> </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 +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 + 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 +. +<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.html b/documentation/Fl_Roller.html index d423d23d0..8c0077269 100644 --- a/documentation/Fl_Roller.html +++ b/documentation/Fl_Roller.html @@ -17,17 +17,17 @@ </PRE> </UL> <H3>Description</H3> - The <TT>Fl_Roller</TT> widget is a "dolly" control commonly used to -move 3D objects. + The <TT>Fl_Roller</TT> widget is a "dolly" control commonly used to +move 3D objects. <P ALIGN=CENTER><IMG src="Fl_Roller.gif" ALT="Fl_Roller widget."></P> <H3>Methods</H3> <UL> <LI><A href=#Fl_Roller.Fl_Roller>Fl_Roller</A></LI> <LI><A href=#Fl_Roller.~Fl_Roller>~Fl_Roller</A></LI> </UL> -<H4><A name=Fl_Roller.Fl_Roller>Fl_Roller::Fl_Roller(int x, int y, int +<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>. + 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 index de82d14d9..f462901c5 100644 --- a/documentation/Fl_Round_Button.html +++ b/documentation/Fl_Round_Button.html @@ -17,14 +17,14 @@ </PRE> </UL> <H3>Description</H3> -Buttons generate callbacks when they are clicked by the user. You +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>. +and <TT>when()</TT>. <P ALIGN=CENTER><IMG SRC="Fl_Round_Button.gif" ALT="Fl_Round_Button widget."></P> -<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 +<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.</P> <H3>Methods</H3> <UL> @@ -32,10 +32,10 @@ FL_RED.</P> <LI><A href=#Fl_Round_Button.~Fl_Round_Button>~Fl_Round_Button</A></LI> </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 +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. + 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.html b/documentation/Fl_Scroll.html index c76b4a94c..5b68214ab 100644 --- a/documentation/Fl_Scroll.html +++ b/documentation/Fl_Scroll.html @@ -17,36 +17,36 @@ </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: + 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 ALIGN=CENTER><IMG src="Fl_Scroll.gif" ALT="Fl_Scroll widget."></P> -<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. +<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 +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> -<P>This widget can also be used to pan around a single child widget +<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. +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=drawing.html#fl_clip><TT>fl_clip()</TT></A> . </P> <P>Another very useful child is a single <A href=Fl_Pack.html#Fl_Pack><TT> -Fl_Pack</TT></A>, which is itself a group that packs it's children +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_Tabs.html#Fl_Tabs><TT>Fl_Tabs</TT></A> groups (and then putting -normal widgets inside those) gives you a very powerful scrolling list + with <A href=Fl_Tabs.html#Fl_Tabs><TT>Fl_Tabs</TT></A> groups (and then putting +normal widgets inside those) gives you a very powerful scrolling list of individually-openable panels. </P> -<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 +<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> -<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 +<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></P> <H3>Methods</H3> <UL> @@ -58,42 +58,42 @@ scrollbars and neighboring objects.</I></P> <LI><A href=#Fl_Scroll.xposition>xposition</A></LI> <LI><A href=#Fl_Scroll.yposition>yposition</A></LI> </UL> -<H4><A name=Fl_Scroll.Fl_Scroll>Fl_Scroll::Fl_Scroll(int x, int y, int +<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>. + 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 + 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. +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 + 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: + can change this: <UL> <LI><TT>0</TT> - No scrollbars </LI> <LI><TT>Fl_Scroll::HORIZONTAL</TT> - Only a horizontal scrollbar. </LI> <LI><TT>Fl_Scroll::VERTICAL</TT> - Only a vertical scrollbar. </LI> <LI><TT>Fl_Scroll::BOTH</TT> - The default is both scrollbars. </LI> -<LI><TT>Fl_Scroll::HORIZONTAL_ALWAYS</TT> - Horizontal scrollbar +<LI><TT>Fl_Scroll::HORIZONTAL_ALWAYS</TT> - Horizontal scrollbar always on, vertical always off. </LI> -<LI><TT>Fl_Scroll::VERTICAL_ALWAYS</TT> - Vertical scrollbar always on, +<LI><TT>Fl_Scroll::VERTICAL_ALWAYS</TT> - Vertical scrollbar always on, horizontal always off. </LI> <LI><TT>Fl_Scroll::BOTH_ALWAYS</TT> - Both always on. </LI> </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. +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. + 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. + 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 index e05de38a5..b1d9123da 100644 --- a/documentation/Fl_Scrollbar.html +++ b/documentation/Fl_Scrollbar.html @@ -17,15 +17,15 @@ </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 + 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 +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 +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>. </P> <P ALIGN=CENTER><IMG src="scrollbar.gif" ALT="Fl_Scrollbar widget."></P> <H3>Methods</H3> @@ -35,26 +35,26 @@ versions of <TT>value()</TT> from <TT>Fl_Slider</TT>. </P> <LI><A href=#Fl_Scrollbar.linesize>linesize</A></LI> <LI><A href=#Fl_Scrollbar.value>value</A></LI> </UL> -<H4><A name=Fl_Scrollbar.Fl_Scrollbar>Fl_Scrollbar::Fl_Scrollbar(int x, +<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 + 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. + 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 + 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. + 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 + 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 + 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 index 62f8ba96e..a861b6069 100644 --- a/documentation/Fl_Secret_Input.html +++ b/documentation/Fl_Secret_Input.html @@ -18,19 +18,19 @@ </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 receive passwords and other "secret" information. + that displays its input as a string of asterisks. This subclass is +usually used to receive passwords and other "secret" information. <H3>Methods</H3> <UL> <LI><A href=#Fl_Secret_Input.Fl_Secret_Input>Fl_Secret_Input</A></LI> <LI><A href=#Fl_Secret_Input.~Fl_Secret_Input>~Fl_Secret_Input</A></LI> </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 +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 + 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 +. +<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 index 002299527..42211e9a9 100644 --- a/documentation/Fl_Select_Browser.html +++ b/documentation/Fl_Select_Browser.html @@ -18,11 +18,11 @@ </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.html#Fl_Browser><TT>Fl_Browser</TT></A> for + 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.html#Fl_Browser><TT>Fl_Browser</TT></A> for methods to add and remove lines from the browser. </P> <H3>Methods</H3> <UL> @@ -33,21 +33,21 @@ methods to add and remove lines from the browser. </P> <LI><A href=#Fl_Select_Browser.value>value</A></LI> </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 +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 + 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 +. +<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>. + 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>. + 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.html#Fl_Multi_Browser> -<TT>Fl_Multi_Browser</TT></A>. If you turn on the selection of more -than one line the results are unpredictable. +<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 + 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 index e10493734..c6bc84bfa 100644 --- a/documentation/Fl_Single_Window.html +++ b/documentation/Fl_Single_Window.html @@ -17,22 +17,22 @@ </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. + 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> <LI><A href=#Fl_Single_Window.~Fl_Single_Window>~Fl_Single_Window</A></LI> </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 +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 + 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 index 80803e97e..c6f51d600 100644 --- a/documentation/Fl_Slider.html +++ b/documentation/Fl_Slider.html @@ -19,11 +19,11 @@ </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>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. +maximum()</TT> to reverse the slider direction. <P ALIGN=CENTER><IMG src="slider.gif" ALT="Fl_Slider widget."></P> <H3>Methods</H3> <UL> @@ -34,45 +34,45 @@ maximum()</TT> to reverse the slider direction. <LI><A href=#Fl_Slider.slider_size>slider_size</A></LI> <LI><A href=#Fl_Slider.type>type</A></LI> </UL> -<H4><A name=Fl_Slider.Fl_Slider>Fl_Slider::Fl_Slider(int x, int y, int +<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_DOWN_BOX</TT>. + Creates a new <TT>Fl_Slider</TT> widget using the given position, +size, and label string. The default boxtype is <TT>FL_DOWN_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 + 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.html#Fl_Scrollbar.value><TT> -Fl_Scrollbar::value()</TT></A>. +Fl_Scrollbar::value()</TT></A>. <H4><A name=Fl_Slider.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>. + 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 + 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. </P> <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: + 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 +<LI><TT>FL_VERTICAL</TT> - Draws a vertical slider (this is the default). </LI> <LI><TT>FL_HORIZONTAL</TT> - Draws a horizontal slider. </LI> -<LI><TT>FL_VERT_FILL_SLIDER</TT> - Draws a filled vertical slider, +<LI><TT>FL_VERT_FILL_SLIDER</TT> - Draws a filled vertical slider, useful as a progress or value meter. </LI> -<LI><TT>FL_HOR_FILL_SLIDER</TT> - Draws a filled horizontal slider, +<LI><TT>FL_HOR_FILL_SLIDER</TT> - Draws a filled horizontal slider, useful as a progress or value meter. </LI> -<LI><TT>FL_VERT_NICE_SLIDER</TT> - Draws a vertical slider with a nice +<LI><TT>FL_VERT_NICE_SLIDER</TT> - Draws a vertical slider with a nice looking control knob. </LI> -<LI><TT>FL_HOR_NICE_SLIDER</TT> - Draws a horizontal slider with a +<LI><TT>FL_HOR_NICE_SLIDER</TT> - Draws a horizontal slider with a nice looking control knob. </LI> </UL> </BODY></HTML> diff --git a/documentation/Fl_Tabs.html b/documentation/Fl_Tabs.html index 69f49f0b8..4e1cfde4f 100644 --- a/documentation/Fl_Tabs.html +++ b/documentation/Fl_Tabs.html @@ -17,26 +17,26 @@ </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. + 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 ALIGN=CENTER><IMG src="tabs.gif" ALT="Fl_Tabs widget."></P> <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.html#Fl_Group> -<TT>Fl_Group</TT></A> widgets containing several widgets +<TT>Fl_Group</TT></A> widgets containing several widgets themselves. </P> -<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.html#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 +<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.html#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> -<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 +<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. </P> <H3>Methods</H3> <UL> @@ -44,21 +44,21 @@ group and resize them until the tabs look the way you want them to. </P> <LI><A href=#Fl_Tabs.~Fl_Tabs>~Fl_Tabs</A></LI> <LI><A href=#Fl_Tabs.value>value</A></LI> </UL> -<H4><A name=Fl_Tabs.Fl_Tabs>Fl_Tabs::Fl_Tabs(int x, int y, int w, int h, +<H4><A name=Fl_Tabs.Fl_Tabs>Fl_Tabs::Fl_Tabs(int x, int y, int w, int h, const char *label = 0)</A></H4> - Creates a new <TT>Fl_Tabs</TT> widget using the given position, size, -and label string. The default boxtype is <TT>FL_THIN_UP_BOX</TT>. + Creates a new <TT>Fl_Tabs</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.html#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 + 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. </P> <H4><A name=Fl_Tabs.~Fl_Tabs>virtual Fl_Tabs::~Fl_Tabs()</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 + 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_Tabs</TT> and all of it's children can be automatic (local) -variables, but you must declare the <TT>Fl_Tabs</TT><I>first</I>, so -that it is destroyed last. +Fl_Tabs</TT> and all of it's children can be automatic (local) +variables, but you must declare the <TT>Fl_Tabs</TT><I>first</I>, so +that it is destroyed last. <H4><A name=Fl_Tabs.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.html b/documentation/Fl_Tile.html index cd2afc2b5..977326308 100644 --- a/documentation/Fl_Tile.html +++ b/documentation/Fl_Tile.html @@ -17,21 +17,21 @@ </PRE> </UL> <H3>Description</H3> - The <TT>Fl_Tile</TT> class lets you resize the children by dragging -the border between them: + The <TT>Fl_Tile</TT> class lets you resize the children by dragging +the border between them: <P ALIGN=CENTER><IMG src="Fl_Tile.gif" ALT="Fl_Tile widget."></P> -<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 +<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> -<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 +<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> <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 + <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. </P> <H3>Methods</H3> <UL> @@ -40,26 +40,26 @@ two adjacent <TT>FL_DOWN_BOX</TT>'s drawn next to each other. </P> <LI><A href=#Fl_Tile.position>position</A></LI> <LI><A href=#Fl_Tile.resizeable>resizeable</A></LI> </UL> -<H4><A name=Fl_Tile.Fl_Tile>Fl_Tile::Fl_Tile(int x, int y, int w, int +<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>. + 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 + 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, +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. + 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 &w)<BR> void Fl_Tile::resizable(Fl_Widget *w)</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 +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 index 1ae611413..489f73d38 100644 --- a/documentation/Fl_Timer.html +++ b/documentation/Fl_Timer.html @@ -17,11 +17,11 @@ </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 + 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=functions.html#add_timeout><TT> -Fl::add_timeout()</TT></A> instead. +Fl::add_timeout()</TT></A> instead. <H3>Methods</H3> <UL> <LI><A href=#Fl_Timer.Fl_Timer>Fl_Timer</A></LI> @@ -30,29 +30,29 @@ Fl::add_timeout()</TT></A> instead. <LI><A href=#Fl_Timer.suspended>suspended</A></LI> <LI><A href=#Fl_Timer.value>value</A></LI> </UL> -<H4><A name=Fl_Timer.Fl_Timer>Fl_Timer::Fl_Timer(uchar type, int x, int +<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: + 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 +<LI><TT>FL_NORMAL_TIMER</TT> - The timer just does the callback and displays the string "Timer" in the widget. </LI> -<LI><TT>FL_VALUE_TIMER</TT> - The timer does the callback and displays +<LI><TT>FL_VALUE_TIMER</TT> - The timer does the callback and displays the current timer value in the widget. </LI> -<LI><TT>FL_HIDDEN_TIMER</TT> - The timer just does the callback and +<LI><TT>FL_HIDDEN_TIMER</TT> - The timer just does the callback and does not display anything. </LI> </UL> <H4><A name=Fl_Timer.~Fl_Timer>virtual Fl_Timer::~Fl_Timer()</A></H4> - Destroys the timer and removes the timeout. + 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>. + 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. + 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 index 2875e30fe..e72d7cce3 100644 --- a/documentation/Fl_Valuator.html +++ b/documentation/Fl_Valuator.html @@ -20,16 +20,16 @@ </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. + 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> <P ALIGN=CENTER><IMG src="valuators.gif" ALT="Fl_Valuator widgets."></P> -<P>In the above diagram each box surrounds an actual subclass. These +<P>In the above diagram each box surrounds an actual subclass. These are further differentiated by setting the <A href=Fl_Widget.html#Fl_Widget.type><TT> -type()</TT></A> of the widget to the symbolic value labeling the +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 +type(0)</TT>. For consistency the symbol <TT>FL_VERTICAL</TT> is defined as zero.</P> <H3>Methods</H3> <CENTER> @@ -66,69 +66,69 @@ defined as zero.</P> </TD></TR> </TABLE> </CENTER> -<H4><A name=Fl_Valuator.Fl_Valuator>Fl_Valuator::Fl_Valuator(int x, int +<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>. + 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. + 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 + 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. + 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. + 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, + 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 + 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> -<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 +<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> -<P>The range may affect the display. You must <TT>redraw()</TT> the +<P>The range may affect the display. You must <TT>redraw()</TT> the widget after changing the range. </P> <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 + 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 +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. </P> <H4><A name=Fl_Valuator.format>int Fl_Valuator::format(char *)</A> </H4> -Format the passed value to show enough digits so that for the current +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. +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. +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 +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>. + 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). + 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> diff --git a/documentation/Fl_Value_Input.html b/documentation/Fl_Value_Input.html index e4fad9208..70766872f 100644 --- a/documentation/Fl_Value_Input.html +++ b/documentation/Fl_Value_Input.html @@ -17,16 +17,16 @@ </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 + 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_Input.html#Fl_Input><TT>Fl_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 +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 +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. </P> <P ALIGN=CENTER><IMG src="Fl_Value_Input.gif" ALT="Fl_Value_Input widget."></P> <H3>Methods</H3> @@ -40,33 +40,33 @@ cursor. </P> <LI><A href=#Fl_Value_Input.textsize>textsize</A></LI> </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 +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_DOWN_BOX</TT>. -<H4><A name=Fl_Value_Input.~Fl_Value_Input>virtual + Creates a new <TT>Fl_Value_Input</TT> widget using the given position, +size, and label string. The default boxtype is <TT>FL_DOWN_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 + 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. + 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 -true. -<H4><A name=Fl_Value_Input.textcolor>Fl_Color + 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 +true. +<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() + 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() + 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.html b/documentation/Fl_Value_Output.html index ca284f3b3..0f03ce632 100644 --- a/documentation/Fl_Value_Output.html +++ b/documentation/Fl_Value_Output.html @@ -17,13 +17,13 @@ </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 + 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>. +100 * step()</TT>. <P>This is much lighter-weight than <A href=Fl_Value_Input.html#Fl_Value_Input> -<TT>Fl_Value_Input</TT></A> because it contains no text editing code or +<TT>Fl_Value_Input</TT></A> because it contains no text editing code or character buffer. </P> <P ALIGN=CENTER><IMG src="Fl_Value_Output.gif" ALT="Fl_Value_Output widget."></P> <H3>Methods</H3> @@ -36,30 +36,30 @@ character buffer. </P> <LI><A href=#Fl_Value_Output.textsize>textsize</A></LI> </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 +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 + 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 +. +<H4><A name=Fl_Value_Output.~Fl_Value_Output>virtual Fl_Value_Output::~Fl_Value_Output()</A></H4> - Destroys the valuator. + 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 + 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 + 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() + 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 index 03dd61c5a..43039c7c6 100644 --- a/documentation/Fl_Value_Slider.html +++ b/documentation/Fl_Value_Slider.html @@ -17,8 +17,8 @@ </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. + The <TT>Fl_Value_Slider</TT> widget is a <TT>Fl_Slider</TT> widget +with a box displaying the current value. <P ALIGN=CENTER><IMG src="value_slider.gif" ALT="Fl_Value_Slider widget."></P> <H3>Methods</H3> <UL> @@ -29,24 +29,24 @@ with a box displaying the current value. <LI><A href=#Fl_Value_Slider.textsize>textsize</A></LI> </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 +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 + 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 +. +<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 + 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 + 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() + 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. diff --git a/documentation/Fl_Widget.html b/documentation/Fl_Widget.html index 394b49c21..99c20db3c 100644 --- a/documentation/Fl_Widget.html +++ b/documentation/Fl_Widget.html @@ -19,15 +19,15 @@ </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.html#subclassing">subclass</A> it. +<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.html#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 +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 +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. </P> <H3>Methods</H3> <CENTER> @@ -95,81 +95,81 @@ to call <TT>redraw()</TT> after these. </P> </TD></TR> </TABLE> </CENTER> -<H4><A NAME="Fl_Widget.Fl_Widget">Fl_Widget::Fl_Widget(int x, int y, int w, int h, const char* +<H4><A NAME="Fl_Widget.Fl_Widget">Fl_Widget::Fl_Widget(int x, int y, int w, int h, const char* label=0);</A></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(). + 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><A NAME="Fl_Widget.~Fl_Widget">virtual Fl_Widget::~Fl_Widget();</A></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. + 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><A NAME="Fl_Widget.type">uchar Fl_Widget::type() const;</A></H4> - This value is used for Forms compatability and to simulate RTTI. + 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 + 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 x, int y, int w, int h)</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 its 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). + Change the size or position of the widget. This is a virtual function +so the widget may implement its 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> . </P> <H4><A name=Fl_Widget.window>Fl_Window* Fl_Widget::window() const;</A></H4> Return a pointer to the <A href=Fl_Window.html#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 <TT>NULL</TT> if none. Note: -for an <TT>Fl_Window</TT>, this returns its <I>parent</I> window (if -any), not <I>this</I> window. +</A> that this widget is in (it will skip any and all parent widgets +between this and the window). Returns <TT>NULL</TT> if none. Note: +for an <TT>Fl_Window</TT>, this returns its <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=common.html#BoxTypes>Box Types</A> for the + The <TT>box()</TT> identifies a routine that draws the background of +the widget. See <A href=common.html#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>. +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 + 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.html#Enumerations> enumeration list</A> for predefined colors. Use <A href=functions.html#set_color> -<TT>Fl::set_color()</TT></A> to redefine colors. -<H4><A name=Fl_Widget.selection_color>Fl_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 + 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>. +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, + 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="common.html#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. + A <A href="common.html#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 + 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: <UL> <LI><TT>FL_ALIGN_CENTER</TT></LI> @@ -183,67 +183,67 @@ can be any of these constants or'd together: </UL> <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>. + 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.html#Enumerations> -enumeration list</A> for predefined typefaces. The default value uses a +enumeration list</A> for predefined typefaces. The default value uses a Helvetica typeface (Arial for Microsoft® Windows®). The function <A href=functions.html#set_font> -<TT>Fl::set_font() </TT></A> can define new typefaces. +<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*, + 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. + 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 + 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 + 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. + 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 + 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. + 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. + 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 +<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 +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. </P> <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</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 + The default callback, which puts a pointer to the widget on the queue returned by <A href=functions.html#readqueue><TT>Fl::readqueue()</TT></A> -. You may want to call this from your own callback. +. 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.visible_r>int Fl_Widget::visible_r() const</A><BR> <A name=Fl_Widget.show>void Fl_Widget::show()</A><BR> @@ -252,12 +252,12 @@ An invisible widget never gets redrawn and does not get events. The <TT>visible()</TT> method returns true if the widget is set to be visible.The <TT>visible_r()</TT> method returns true if the widget and all of its parents are visible. A widget is only visible if -<TT>visible()</TT> is true on it <I>and all of its parents</I>. +<TT>visible()</TT> is true on it <I>and all of its parents</I>. <P>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 +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. + 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.active_r>int Fl_Widget::active_r() const</A></BR> <A name=Fl_Widget.activate>void Fl_Widget::activate()</A></BR> @@ -284,11 +284,11 @@ displays rather than input devices. This is the same as <TT>(active() && visible() && !output())</TT> but is faster. <H4><A name=Fl_Widget.redraw>void Fl_Widget::redraw()</A></H4> - Mark the widget as needing its <A HREF="subclassing.html#draw"><TT>draw()</TT></A> routine called. + Mark the widget as needing its <A HREF="subclassing.html#draw"><TT>draw()</TT></A> routine called. <H4><A name=Fl_Widget.damage>uchar Fl_Widget::damage() const</A></H4> - Non-zero if <A HREF="subclassing.html#draw"><TT>draw()</TT></A> needs to be called. Actually this is a -bit field that the widget subclass can use to figure out what parts to -draw. + Non-zero if <A HREF="subclassing.html#draw"><TT>draw()</TT></A> 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_Group *Fl_Widget::parent() const</A></H4> Returns a pointer to the parent widget. Usually this is a <A href=Fl_Group.html#Fl_Group> <TT>Fl_Group</TT></A> or <A @@ -297,14 +297,14 @@ HREF="Fl_Window.html#Fl_Window"><tt>Fl_Window</tt></a>. Returns <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) +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>. +. Returns false if <TT>a</TT> is <TT>NULL</TT>. <H4><A name=Fl_Widget.take_focus>int Fl_Widget::take_focus()</A></H4> - Tries to make this widget be the <TT>Fl::focus()</TT> widget, by first -sending it an <TT>FL_FOCUS</TT> event, and if it returns non-zero, -setting <TT>Fl::focus()</TT> to this widget. You should use this -method to assign the focus to an widget. Returns true if the widget + Tries to make this widget be the <TT>Fl::focus()</TT> widget, by first +sending it an <TT>FL_FOCUS</TT> event, and if it returns non-zero, +setting <TT>Fl::focus()</TT> to this widget. You should use this +method to assign the focus to an widget. Returns true if the widget accepted the focus. </BODY></HTML> diff --git a/documentation/Fl_Window.html b/documentation/Fl_Window.html index 2323a38e3..a245e2d52 100644 --- a/documentation/Fl_Window.html +++ b/documentation/Fl_Window.html @@ -20,17 +20,17 @@ </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>. + 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.html#Fl_Group><TT>Fl_Group</TT></A> for more information +href=Fl_Group.html#Fl_Group><TT>Fl_Group</TT></A> for more information on how to add and remove children. </P> -<P>There are several subclasses of <TT>Fl_Window</TT> that provide +<P>There are several subclasses of <TT>Fl_Window</TT> that provide double-buffering, overlay, menu, and OpenGL support. </P> -<P>The window's callback is done if the user tries to close a window +<P>The window's callback is done if the user tries to close a window using the window manager and <A href=functions.html#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>. </P> @@ -89,9 +89,9 @@ place to show the window or allow the user to pick a location. If you want to force a position you should call <tt>position(x,y)</tt> or <tt>hotspot()</tt> before calling <tt>show()</tt>. -<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 +<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>. </P> <h4>Fl_Window::Fl_Window(int x, int y, int w, int h, const char *title = 0)</H4> @@ -100,157 +100,157 @@ you may want to change this to <TT>FL_UP_BOX</TT>. </P> leaves <tt>visible()</tt> set to true. <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 + 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, +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. + 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 +<LI><TT>minw</TT> and <TT>minh</TT> are the smallest the window can be. </LI> -<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 +<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> -<LI><TT>dw</TT> and <TT>dh</TT> are size increments. The window will +<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 + is any non-negative integer. If these are less or equal to 1 they are ignored. (this is ignored on WIN32)</LI> -<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 +<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. (ignored on WIN32 and by many X window managers)</LI> </UL> - If this function is not called, FLTK tries to figure out the range + If this function is not called, FLTK tries to figure out the range from the setting of <A href="Fl_Group.html#Fl_Group.resizable"><TT>resizable()</TT></A>: <UL> -<LI>If <TT>resizable()</TT> is <TT>NULL</TT> (this is the default) -then the window cannot be resized and the resize border and max-size +<LI>If <TT>resizable()</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> -<LI>If either dimension of <TT>resizable()</TT> is less than 100, +<LI>If either dimension of <TT>resizable()</TT> is less than 100, then that is considered the minimum size. Otherwise the <TT> resizable()</TT> has a minimum size of 100. </LI> -<LI>If either dimension of <TT>resizable()</TT> is zero, then that is +<LI>If either dimension of <TT>resizable()</TT> is zero, then that is also the maximum size (so the window cannot resize in that direction). </LI> </UL> - It is undefined what happens if the current size does not fit in the -constraints passed to <TT>size_range()</TT>. + 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> 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 form is used for top-level -windows and allow standard arguments to be parsed from the +Put the window on the screen. Usually this has the side effect of +opening the display. The second form is 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 +<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. </P> <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 + Remove the window from the screen. If the window is already hidden or has not been shown then this does nothing and is harmless. <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>. +). 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. + 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> -<P>When a window is iconified/restored (either by these calls or by the +<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> -<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 +<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. </P> <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.html#Fl_Group><TT>Fl_Group</TT></A> for the effect -of resizing on the child widgets. + 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.html#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 + and <TT>position(w,h)</TT>, which are inline wrappers for this virtual function. </P> <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 + 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_Widgetp, 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). +<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 + 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>. +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 + 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. +<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 + 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=functions.html#modal><TT> -Fl::modal()</TT></A>. +Fl::modal()</TT></A>. <H4><A name=Fl_Window.modal>uchar Fl_Window::modal() const</A></H4> - Returns true if this window is modal. + 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. + 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. + 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. + 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. + 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", + 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>. +before</I> calling <TT>show()</TT>. <P>Under Microsoft Windows this string is used as the name of the WNDCLASS structure, though it is not clear if this can have any visible effect. </P> <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.html#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 +href=drawing.html#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. </P> diff --git a/documentation/basics.html b/documentation/basics.html index cf2f1eaf9..983f1a6cb 100644 --- a/documentation/basics.html +++ b/documentation/basics.html @@ -33,7 +33,7 @@ int main(int argc, char **argv) { } </PRE></UL> -<P>After including the required header files, the program then creates a +<P>After including the required header files, the program then creates a window:</P> <UL><PRE> @@ -116,7 +116,7 @@ of the form "type name() const".</P> <P>Almost all of the set/get pairs are very fast, short inline functions and thus very efficient. However, <i>the "set" methods do not call <TT>redraw()</TT></i> - you have to call it -yourself. This greatly reduces code size and execution time. +yourself. This greatly reduces code size and execution time. The only common exception is <tt>value()</tt> which calls <TT>redraw()</TT> if necessary.</P> @@ -144,8 +144,8 @@ desired.</P> <H3>Showing the Window</H3> -<P>The <TT>show()</TT> method shows the widget or window. For windows -you can also provide the command-line arguments to allow users to +<P>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.</P> <H3>The Main Event Loop</H3> @@ -192,8 +192,8 @@ under FLTK control are closed by the user or your program.</P> <H2>Compiling Programs with Standard Compilers</H2> -<P>Under UNIX (and under Microsoft Windows when using the GNU development -tools) you will probably need to tell the compiler where to find the +<P>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:</P> <UL><PRE> @@ -208,7 +208,7 @@ used to get the options that are required by your compiler:</P> CC `fltk-config --cxxflags` ... </PRE></UL> -<P>Similarly, when linking your application you will need to tell the +<P>Similarly, when linking your application you will need to tell the compiler to use the FLTK library:</P> <UL><PRE> @@ -228,18 +228,18 @@ CC ... `fltk-config --ldflags` <P>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 +changing the "Preprocessor" settings under the "C/C++" tab. You will also need to add the FLTK and WinSock (WSOCK32.LIB) libraries to the "Link" settings.</P> -<P>You can build your Microsoft Windows applications as Console or +<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, FLTK includes a <TT>WinMain()</TT> function that will call your <TT>main()</TT> function for you.</P> -<P><I>Note: The Visual C++ 5.0 optimizer is known to cause problems with -many programs. We only recommend using the "Favor Small Code" +<P><I>Note: The Visual C++ 5.0 optimizer is known to cause problems with +many programs. We only recommend using the "Favor Small Code" optimization setting.</I> The Visual C++ 6.0 optimizer seems to be much better and can be used with the "optimized for speed" setting.</P> diff --git a/documentation/common.html b/documentation/common.html index e05bdfbc8..61628b403 100644 --- a/documentation/common.html +++ b/documentation/common.html @@ -120,12 +120,12 @@ value, instead of a simple string.</P> <H2>Valuators</H2> -<P>Unlike text widgets, valuators keep track of numbers instead of +<P>Unlike text widgets, valuators keep track of numbers instead of strings. FLTK provides the following valuators:</P> <UL> - <LI><A HREF="Fl_Counter.html"><TT>Fl_Counter</TT></A> - A widget with arrow buttons that shows the + <LI><A HREF="Fl_Counter.html"><TT>Fl_Counter</TT></A> - A widget with arrow buttons that shows the current value. </LI> <LI><A HREF="Fl_Dial.html"><TT>Fl_Dial</TT></A> - A round knob. </LI> @@ -164,7 +164,7 @@ with FLTK:</P> <LI><A HREF="Fl_Gl_Window.html"><TT>Fl_Gl_Window</TT></A> - An OpenGL window on the screen. </LI> - <LI><A HREF="Fl_Group.html"><TT>Fl_Group</TT></A> - The base container class; can be used to group + <LI><A HREF="Fl_Group.html"><TT>Fl_Group</TT></A> - The base container class; can be used to group any widgets together. </LI> <LI><A HREF="Fl_Packed.html"><TT>Fl_Pack</TT></A> - A collection of widgets that are packed into the group area.</LI> @@ -259,14 +259,14 @@ Figure 3-3 shows the standard box types included with FLTK.</P> <P ALIGN="CENTER"><IMG src="boxtypes.gif" ALT="FLTK Box Types"><BR> <I>Figure 3-3: FLTK box types</I></P> -<P><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 +<P><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 interior unchanged. The blue color in Figure 3-3 is the area that is not drawn by the frame types.</P> <H3>Making Your Own Boxtypes</H3> -<P>You can define your own boxtypes by making a small function that draws +<P>You can define your own boxtypes by making a small function that draws the box and adding it to the table of boxtypes.</P> <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> @@ -279,7 +279,7 @@ the box and adding it to the table of boxtypes.</P> <H4>The Drawing Function</H4> -<P>The drawing function is passed the bounding box and background color +<P>The drawing function is passed the bounding box and background color for the widget:</P> <UL><PRE> @@ -350,7 +350,7 @@ sign. Figure 3-4 shows the available symbols.</P> <H3>align()</H3> -<P>The <TT>align()</TT> method positions the label. The following +<P>The <TT>align()</TT> method positions the label. The following constants are defined and may be OR'd together as needed:</P> <UL> @@ -359,17 +359,17 @@ constants are defined and may be OR'd together as needed:</P> <LI><TT>FL_ALIGN_TOP</TT> - align the label at the top of the widget.</LI> - <LI><TT>FL_ALIGN_BOTTOM</TT> - align the label at the bottom of the + <LI><TT>FL_ALIGN_BOTTOM</TT> - align the label at the bottom of the widget.</LI> <LI><TT>FL_ALIGN_LEFT</TT> - align the label to the left of the widget.</LI> - <LI><TT>FL_ALIGN_RIGHT</TT> - align the label to the right of the + <LI><TT>FL_ALIGN_RIGHT</TT> - align the label to the right of the widget.</LI> <LI><TT>FL_ALIGN_INSIDE</TT> - align the label inside the widget.</LI> - <LI><TT>FL_ALIGN_CLIP</TT> - clip the label to the widget's bounding + <LI><TT>FL_ALIGN_CLIP</TT> - clip the label to the widget's bounding box.</LI> <LI><TT>FL_ALIGN_WRAP</TT> - wrap the label text as needed.</LI> @@ -382,7 +382,7 @@ constants are defined and may be OR'd together as needed:</P> <H3><A NAME="labeltypes">labeltype()</A></H3> -<P>The <TT>labeltype()</TT> method sets the type of the label. The +<P>The <TT>labeltype()</TT> method sets the type of the label. The following standard label types are included:</P> <UL> @@ -478,7 +478,7 @@ 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> -<P>The <TT>Fl::set_labeltype</TT> method can also be used to overload +<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>.</P> <H2>Callbacks</H2> @@ -494,8 +494,8 @@ void xyz_callback(Fl_Widget *w, void *data) { } </PRE></UL> -<P>The <TT>callback()</TT> method sets the callback function for a -widget. You can optionally pass a pointer to some data needed for the +<P>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:</P> <UL><PRE> diff --git a/documentation/drawing.html b/documentation/drawing.html index 737d8264e..30a359247 100644 --- a/documentation/drawing.html +++ b/documentation/drawing.html @@ -1,90 +1,176 @@ -<HTML><BODY> -<H1><A NAME=drawing>5 - Drawing Things in FLTK</A></H1> - This chapter covers the drawing functions that are provided with FLTK. +<HTML> +<BODY> + +<H1><A NAME="drawing">5 - Drawing Things in FLTK</A></H1> + +<P>This chapter covers the drawing functions that are provided with FLTK. + <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! + +<P>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="subclassing.html#draw"><TT> -Fl_Widget::draw()</TT></A>. To write code here, you must subclass one -of the existing <TT>Fl_Widget</TT> classes and implement your own -version of <TT>draw()</TT>. </LI> -<LI>You can also write <A href=common.html#boxtypes>boxtypes</A> and <A href="common.html#labeltypes"> -labeltypes</A>. These are small procedures that can be called by -existing <A HREF="subclassing.html#draw"><TT>Fl_Widget::draw()</TT></A> methods. These "types" are -identified by an 8-bit index that is stored in the widget's <TT>box()</TT>, -<TT>labeltype()</TT>, and possibly other properties. </LI> -<LI>You can call <A href=Fl_Window.html#Fl_Window.make_current><TT> -Fl_Window::make_current()</TT></A> to do incremental update of a -widget. Use <A href=Fl_Widget.html#Fl_Widget.window><TT> -Fl_Widget::window()</TT></A> to find the window.</LI> + + <LI>The most common place is inside the virtual method + <A + href="subclassing.html#draw"><TT>Fl_Widget::draw()</TT></A>. + To write code here, you must subclass one of the + existing <TT>Fl_Widget</TT> classes and implement your + own version of <TT>draw()</TT>.</LI> + + <LI>You can also write <A + href="common.html#boxtypes">boxtypes</A> and <A + href="common.html#labeltypes">labeltypes</A>. These are + small procedures that can be called by existing <A + HREF="subclassing.html#draw"><TT>Fl_Widget::draw()</TT></A> + methods. These "types" are identified by an + 8-bit index that is stored in the widget's + <TT>box()</TT>, <TT>labeltype()</TT>, and possibly other + properties.</LI> + + <LI>You can call <A + href="Fl_Window.html#Fl_Window.make_current"><TT>Fl_Window::make_current()</TT></A> + to do incremental update of a widget. Use <A + href=Fl_Widget.html#Fl_Widget.window><TT>Fl_Widget::window()</TT></A> + to find the window.</LI> + </UL> + <H2>FLTK Drawing Functions</H2> - To use the drawing functions you must first include the <TT> -<FL/fl_draw.H></TT> header file. FLTK provides the following types of -drawing functions: + +<P>To use the drawing functions you must first include the +<TT><FL/fl_draw.H></TT> header file. FLTK provides the +following types of drawing functions: + <UL> -<LI><A href=#clipping>Clipping</A></LI> -<LI><A href=#colors>Colors</A></LI> -<LI><A href=#lines>Line dashes and thickness</A></LI> -<LI><A href=#fast>Fast Shapes</A></LI> -<LI><A href=#complex>Complex Shapes</A></LI> -<LI><A href=#text>Text</A></LI> -<LI><A href=#images>Images</A></LI> -<LI><A href=#overlay>Overlay</A></LI> + + <LI><A href="#clipping">Clipping</A></LI> + + <LI><A href="#colors">Colors</A></LI> + + <LI><A href="#lines">Line dashes and thickness</A></LI> + + <LI><A href="#fast">Fast Shapes</A></LI> + + <LI><A href="#complex">Complex Shapes</A></LI> + + <LI><A href="#text">Text</A></LI> + + <LI><A href="#images">Images</A></LI> + + <LI><A href="#overlay">Overlay</A></LI> + </UL> -<H3><A name=clipping>Clipping</A></H3> - You can limit all your drawing to a rectangular region by calling <TT> -fl_clip</TT>, and put the drawings back by using <TT>fl_pop_clip</TT>. - 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. </P> + +<H3><A name="clipping">Clipping</A></H3> + +<P>You can limit all your drawing to a rectangular region by calling +<TT>fl_clip</TT>, and put the drawings back by using <TT>fl_pop_clip</TT>. +This rectangle is measured in pixels and is unaffected by the current +transformation matrix. + +<P>In addition, the system may provide clipping when updating windows +which may be more complex than a simple rectangle.</P> + <H4>void fl_push_clip(int x, int y, int w, int h)</H4> -Intersect the current clip region with a rectangle and push this new -region onto the stack. + +<P>Intersect the current clip region with a rectangle and push this new +region onto the stack. + <H4>void fl_push_no_clip()</H4> -Pushes an empty clip region on the stack so nothing will be clipped. + +<P>Pushes an empty clip region on the stack so nothing will be clipped. + <H4>void fl_pop_clip()</H4> -Restore the previous clip region. <I>You must call <TT>fl_pop_clip()</TT> -once for every time you call <TT>fl_clip()</TT>. If you return to -FLTK with the clip stack not empty unpredictable results occur.</I> + +<P>Restore the previous clip region. + +<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> +<TR> + <TD><B>Note:</B> + + <P>You must call <TT>fl_pop_clip()</TT> once for every + time you call <TT>fl_clip()</TT>. If you return to FLTK + with the clip stack not empty unpredictable results + occur. + + </TD> +</TR> +</TABLE></CENTER> + <H4>int fl_not_clipped(int x, int y, int w, int h)</H4> -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> -Under X this returns 2 if the rectangle is partially clipped, and 1 if -it is entirely inside the clip region</I>. -<H4>int fl_clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, + +<P>Returns non-zero if any of the rectangle intersects the current clip +region. If this returns 0 you don't have to draw the object. + +<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> +<TR> + <TD><B>Note:</B> + + <P>Under X this returns 2 if the rectangle is partially + clipped, and 1 if it is entirely inside the clip region. + + </TD> +</TR> +</TABLE></CENTER> + +<H4>int fl_clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, int &H)</H4> -Intersect the rectangle <TT>x,y,w,h</TT> with the current clip region -and returns the bounding box of the result in <TT>X,Y,W,H</TT>. -Returns non-zero if the resulting rectangle is different than the -original. This can be used to limit the necessary drawing to a -rectangle. <TT>W</TT> and <TT>H</TT> are set to zero if the rectangle -is completely outside the region. -<H3><A name=colors>Colors</A></H3> + +<P>Intersect the rectangle <TT>x,y,w,h</TT> with the current +clip region and returns the bounding box of the result in +<TT>X,Y,W,H</TT>. Returns non-zero if the resulting rectangle is +different than the original. This can be used to limit the +necessary drawing to a rectangle. <TT>W</TT> and <TT>H</TT> are +set to zero if the rectangle is completely outside the region. + +<H3><A name="colors">Colors</A></H3> + +<P>FLTK manages colors as 32-bit unsigned integers. Values from +0 to 255 represent colors from the FLTK 1.0.x standard colormap +and are allocated as needed on screens without TrueColor +support. The <TT>Fl_Color</TT> enumeration type defines the +standard colors and color cube for the first 256 colors. All of +these are named with symbols in <A +href="enumerations.html#colors"><TT><FL/Enumerations.H></TT></A>. + +<P>Color values greater than 255 are treated as 24-bit RGB +values. These are mapped to the closest color supported by the +screen, either from one of the 256 colors in the FLTK 1.0.x +colormap or a direct RGB value on TrueColor screens. You can +generate 24-bit RGB color values using the <A +HREF="functions.html#fl_rgb_color"><TT>fl_rgb_color()</TT> +function. + <H4>void fl_color(Fl_Color)</H4> - Set the color for all subsequent drawing operations. <TT>Fl_Color</TT> - is an enumeration type, and all values are in the range 0-255. This -is <I>not</I> the X or WIN32 pixel, it is an index into 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 -symbols in <A href=enumerations.html#colors> -<TT><FL/Enumerations.H></TT></A>. -<P>For colormapped displays, a color cell will be allocated out of <TT> -fl_colormap</TT> the first time you use a color. If the colormap fills -up then a least-squares algorithm is used to find the closest color. </P> + +<P>Sets the color for all subsequent drawing operations. + +<P>For colormapped displays, a color cell will be allocated out +of <TT>fl_colormap</TT> the first time you use a color. If the +colormap fills up then a least-squares algorithm is used to find +the closest color.</P> + <H4>Fl_Color fl_color()</H4> - Returns the last <TT>fl_color()</TT> that was set. This can be used -for state save/restore. + +<P>Returns the last <TT>fl_color()</TT> that was set. This can +be used for state save/restore. + <H4>void fl_color(uchar r, uchar g, uchar b)</H4> - Set the color for all subsequent drawing operations. The closest -possible match to the RGB color is used. The RGB color is used -directly on TrueColor displays. For colormap visuals the nearest index -in the gray ramp or color cube is used. -<h3><A name=lines>Line dashes and thickness</a></h3> +<P>Set the color for all subsequent drawing operations. The +closest possible match to the RGB color is used. The RGB color +is used directly on TrueColor displays. For colormap visuals the +nearest index in the gray ramp or color cube is used. + +<h3><A name="lines">Line Dashes and Thickness</a></h3> + +<P>FLTK supports drawing of lines with different styles and +widths. Full functionality is not available under Windows 95, 98, +and Me due to the reduced drawing functionality these operating +systems provide. <h4>void fl_line_style(int style, int width=0, char* dashes=0)</h4> @@ -92,431 +178,617 @@ in the gray ramp or color cube is used. responsibility to set it back to the default with <tt>fl_line_style(0)</tt>. -<BLOCKQUOTE> -<B>Note:</B> Because of how line styles are implemented on WIN32 systems, -you <I>must</I> set the line style <I>after</I> setting the drawing color. -If you set the color after the line style you will lose the line style -settings! -</BLOCKQUOTE> +<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> +<TR> + <TD><B>Note:</B> -<p><i>style</i> is a bitmask in which you 'or' the following values. If -you don't specify a dash type you will get a solid line. If you don't -specify a cap or join type you will get a system-defined default of -whatever value is fastest. + <P>Because of how line styles are implemented on WIN32 + systems, you <I>must</I> set the line style <I>after</I> + setting the drawing color. If you set the color after + the line style you will lose the line style settings! + + </TD> +</TR> +</TABLE></CENTER> + +<P><i>style</i> is a bitmask which is a bitwise-OR of the following +values. If you don't specify a dash type you will get a solid +line. If you don't specify a cap or join type you will get a +system-defined default of whatever value is fastest. <ul> -<li><tt>FL_SOLID -------</tt> -<li><tt>FL_DASH - - - -</tt> -<li><tt>FL_DOT .......</tt> -<li><tt>FL_DASHDOT - . - .</tt> -<li><tt>FL_DASHDOTDOT - .. -</tt> -<li><tt>FL_CAP_FLAT</tt> -<li><tt>FL_CAP_ROUND</tt> -<li><tt>FL_CAP_SQUARE</tt> (extends past end point 1/2 line width) -<li><tt>FL_JOIN_MITER</tt> (pointed) -<li><tt>FL_JOIN_ROUND</tt> -<li><tt>FL_JOIN_BEVEL</tt> (flat) + + <li><tt>FL_SOLID -------</tt> + + <li><tt>FL_DASH - - - -</tt> + + <li><tt>FL_DOT .......</tt> + + <li><tt>FL_DASHDOT - . - .</tt> + + <li><tt>FL_DASHDOTDOT - .. -</tt> + + <li><tt>FL_CAP_FLAT</tt> + + <li><tt>FL_CAP_ROUND</tt> + + <li><tt>FL_CAP_SQUARE</tt> (extends past end point 1/2 line width) + + <li><tt>FL_JOIN_MITER</tt> (pointed) + + <li><tt>FL_JOIN_ROUND</tt> + + <li><tt>FL_JOIN_BEVEL</tt> (flat) + </ul> -<p><i>width</i> is the number of pixels thick to draw the lines. Zero -results in the system-defined default, which on both X and Windows is -somewhat different and nicer than 1. +<P><i>width</i> is the number of pixels thick to draw the lines. +Zero results in the system-defined default, which on both X and +Windows is somewhat different and nicer than 1. -<p><i>dashes</i> is a pointer to an array of dash lengths, measured in +<P><i>dashes</i> is a pointer to an array of dash lengths, measured in pixels. The first location is how long to draw a solid portion, the next is how long to draw the gap, then the solid, etc. It is -terminated with a zero-length entry. A null pointer or a zero-length -array results in a solid line. Odd array sizes are not supported and -result in undefined behavior. <i>The dashes array does not work on -Windows 95/98, use the dash styles instead.</i> - -<H3><A name=fast>Fast Shapes</A></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=#complex> -transformation matrix</A>, so you should only call these while it is -the identity. +terminated with a zero-length entry. A <TT>NULL</TT> pointer or a zero-length +array results in a solid line. Odd array sizes are not supported and +result in undefined behavior. + +<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> +<TR> + <TD><B>Note:</B> + + <P>The dashes array does not work under Windows 95, 98, + or Me, since those operating systems do not support + complex line styles. + + </TD> +</TR> +</TABLE></CENTER> + +<H3><A name="fast">Drawing Fast Shapes</A></H3> + +<P>These functions are used to draw almost all the FLTK widgets. +They draw on exact pixel boundaries and are as fast as possible. +Their behavior is duplicated exactly on all platforms FLTK is +ported. It is undefined whether these are affected by the <A +href="#complex">transformation matrix</A>, so you should only +call these while the matrix is set to the identity matrix (the +default). + <H4>void fl_point(int x, int y)</H4> -Draw a single pixel at the given coordinates. + +<P>Draw a single pixel at the given coordinates. + <H4>void fl_rectf(int x, int y, int w, int h)</H4> - Color a rectangle that exactly fills the given bounding box. + +<P>Color a rectangle that exactly fills the given bounding box. + <H4>void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b)</H4> - Color a rectangle with "exactly" the passed <TT>r,g,b</TT> color. On -screens with less than 24 bits of color this is done by drawing a -solid-colored block using <A href=#fl_draw_image><TT>fl_draw_image()</TT> -</A> so that dithering is produced. + +<P>Color a rectangle with "exactly" the passed +<TT>r,g,b</TT> color. On screens with less than 24 bits of +color this is done by drawing a solid-colored block using <A +href="#fl_draw_image"><TT>fl_draw_image()</TT></A> so that +the correct color shade is produced. + <H4>void fl_rect(int x, int y, int w, int h)</H4> - Draw a 1-pixel border <I>inside</I> this bounding box. + +<P>Draw a 1-pixel border <I>inside</I> this bounding box. + <H4>void fl_line(int x, int y, int x1, int y1) -<BR> void fl_line(int x, int y, int x1, int y1, int x2, int y2)</H4> - Draw one or two 1-pixel thick lines between the given points. +<BR>void fl_line(int x, int y, int x1, int y1, int x2, int y2)</H4> + +<P>Draw one or two lines between the given points. + <H4>void fl_loop(int x, int y, int x1, int y1, int x2, int y2) -<BR> void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, +<BR>void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3)</H4> - Outline a 3 or 4-sided polygon with 1-pixel thick lines. + +<P>Outline a 3 or 4-sided polygon with lines. + <H4>void fl_polygon(int x, int y, int x1, int y1, int x2, int y2) -<BR> void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int +<BR>void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3)</H4> - Fill a 3 or 4-sided polygon. The polygon must be convex. + +<P>Fill a 3 or 4-sided polygon. The polygon must be convex. + <H4>void fl_xyline(int x, int y, int x1, int y1) -<BR> void fl_xyline(int x, int y, int x1, int y1, int x2) -<BR> void fl_xyline(int x, int y, int x1, int y1, int x2, int y3)</H4> - Draw 1-pixel wide horizontal and vertical lines. A horizontal line is -drawn first, then a vertical, then a horizontal. +<BR>void fl_xyline(int x, int y, int x1, int y1, int x2) +<BR>void fl_xyline(int x, int y, int x1, int y1, int x2, int y3)</H4> + +<P>Draw horizontal and vertical lines. A horizontal line is +drawn first, then a vertical, then a horizontal. + <H4>void fl_yxline(int x, int y, int y1) -<BR> void fl_yxline(int x, int y, int y1, int x2) -<BR> void fl_yxline(int x, int y, int y1, int x2, int y3)</H4> - Draw 1-pixel wide vertical and horizontal lines. A vertical line is -drawn first, then a horizontal, then a vertical. +<BR>void fl_yxline(int x, int y, int y1, int x2) +<BR>void fl_yxline(int x, int y, int y1, int x2, int y3)</H4> + +<P>Draw vertical and horizontal lines. A vertical line is drawn +first, then a horizontal, then a vertical. + <H4>void fl_arc(int x, int y, int w, int h, double a1, double a2) -<BR> void fl_pie(int x, int y, int w, int h, double a1, double a2)</H4> - High-speed ellipse sections. These functions match the rather limited -circle drawing code provided by X and WIN32. The advantage over -using <A href=#fl_arc><TT>fl_arc</TT></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 +<BR>void fl_pie(int x, int y, int w, int h, double a1, double a2)</H4> + +<P>Draw ellipse sections using integer coordinates. These +functions match the rather limited circle drawing code provided +by X and WIN32. The advantage over using <A +href="#fl_arc"><TT>fl_arc</TT></A> with floating point +coordinates 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, <TT>a2</TT> - must be greater or equal to <TT>a1</TT>. </P> -<P><TT>fl_arc()</TT> draws a 1-pixel thick line (notice this has a -different number of arguments than the <A href=#fl_arc><TT>fl_arc()</TT></A> - described below. </P> -<P><TT>fl_pie()</TT> draws a filled-in pie slice. This slice may -extend outside the line drawn by <TT>fl_arc</TT>, to avoid this use <TT> -w - 1</TT> and <TT>h - 1</TT>. </P> -<H3><A name=complex>Complex Shapes</A></H3> - These functions let you draw arbitrary shapes with 2-D linear -transformations. The functionality matches that found in Adobe® -PostScript<SUP>TM</SUP>. The exact pixels that are filled is less defined -than for the previous calls so that FLTK can take advantage of drawing -hardware. On both X and WIN32 the transformed vertices are rounded to integers before -drawing the line segments: this severely limits the accuracy of these -functions for complex graphics, so use OpenGL when greater accuracy -and/or performance is required. +must be greater or equal to <TT>a1</TT>.</P> + +<P><TT>fl_arc()</TT> draws a series of lines to approximate the arc. +Notice that the integer version of <TT>fl_arc()</TT> has a different +number of arguments than the <A href="#fl_arc"><TT>fl_arc()</TT></A> +function described later in this chapter.</P> + +<P><TT>fl_pie()</TT> draws a filled-in pie slice. This slice may +extend outside the line drawn by <TT>fl_arc</TT>; to avoid this +use <TT>w - 1</TT> and <TT>h - 1</TT>.</P> + +<H3><A name="complex">Drawing Complex Shapes</A></H3> + +<P>The complex drawing functions let you draw arbitrary shapes +with 2-D linear transformations. The functionality matches that +found in the Adobe® PostScript<SUP>TM</SUP> language. The +exact pixels that are filled are less defined than for the fast +drawing functions so that FLTK can take advantage of drawing +hardware. On both X and WIN32 the transformed vertices are +rounded to integers before drawing the line segments: this +severely limits the accuracy of these functions for complex +graphics, so use OpenGL when greater accuracy and/or performance +is required. + <H4>void fl_push_matrix() -<BR> void fl_pop_matrix()</H4> - Save and restore the current transformation. The maximum depth of the -stack is 4. +<BR>void fl_pop_matrix()</H4> + +<P>Save and restore the current transformation. The maximum +depth of the stack is 4. + <H4>void fl_scale(float x, float y) -<BR> void fl_scale(float x) -<BR> void fl_translate(float x, float y) -<BR> void fl_rotate(float d) -<BR> void fl_mult_matrix(float a, float b, float c, float d, float -x, float y)</H4> - Concatenate another transformation onto the current one. The rotation -angle is in degrees (not radians) and is counter-clockwise. +<BR>void fl_scale(float x) +<BR>void fl_translate(float x, float y) +<BR>void fl_rotate(float d) +<BR>void fl_mult_matrix(float a, float b, float c, float d, float +x, float y)</H4> + +<P>Concatenate another transformation onto the current one. The rotation +angle is in degrees (not radians) and is counter-clockwise. + <H4>void fl_begin_line() -<BR> void fl_end_line()</H4> - Start and end drawing 1-pixel thick lines. +<BR>void fl_end_line()</H4> + +<P>Start and end drawing lines. + <H4>void fl_begin_loop() <BR> void fl_end_loop()</H4> - Start and end drawing a closed sequence of 1-pixel thick lines. + +<P>Start and end drawing a closed sequence of lines. + <H4>void fl_begin_polygon() -<BR> void fl_end_polygon()</H4> - Start and end drawing a convex filled polygon. +<BR>void fl_end_polygon()</H4> + +<P>Start and end drawing a convex filled polygon. + <H4>void fl_begin_complex_polygon() -<BR> void fl_gap() -<BR> void fl_end_complex_polygon()</H4> - 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 <TT>fl_gap()</TT> to seperate loops of the path (it is unnecessary -but harmless to call <TT>fl_gap()</TT> 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. +<BR>void fl_gap() +<BR>void fl_end_complex_polygon()</H4> + +<P>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 <TT>fl_gap()</TT> to seperate loops of +the path. It is unnecessary but harmless to call +<TT>fl_gap()</TT> before the first vertex, after the last one, +or several times in a row. + +<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> +<TR> + <TD><B>Note:</B> + + <P>For portability, you should only draw polygons that + appear the same whether "even/odd" or + "non-zero" winding rules are used to fill + them. Holes should be drawn in the opposite direction of + the outside loop. + + </TD> +</TR> +</TABLE></CENTER> + <P><TT>fl_gap()</TT> should only be called between <TT> -fl_begin_complex_polygon()</TT> and <TT>fl_end_complex_polygon()</TT>. - To outline the polygon, use <TT>fl_begin_loop()</TT> and replace each <TT> -fl_gap()</TT> with <TT>fl_end_loop();fl_begin_loop()</TT>.</P> +fl_begin_complex_polygon()</TT> and +<TT>fl_end_complex_polygon()</TT>. To outline the polygon, use +<TT>fl_begin_loop()</TT> and replace each <TT>fl_gap()</TT> with +<TT>fl_end_loop();fl_begin_loop()</TT>.</P> + <H4>void fl_vertex(float x, float y)</H4> - Add a single vertex to the current path. -<H4>void fl_curve(float x, float y, float x1, float y1, float x2, float +Add a single vertex to the current path. + +<H4>void fl_curve(float x, float y, float x1, float y1, float x2, float y2, float x3, float y3)</H4> - Add a series of points on a Bezier curve to the path. The curve ends -(and two of the points) are at <TT>x,y</TT> and <TT>x3,y3</TT>. + +<P>Add a series of points on a Bezier curve to the path. The curve ends +(and two of the points) are at <TT>x,y</TT> and <TT>x3,y3</TT>. + <H4><A NAME="fl_arc">void fl_arc(float x, float y, float r, float start, float end)</A></H4> - 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). <TT>x,y</TT> are the center of the circle, and <TT>r</TT> is its -radius. <TT>fl_arc()</TT> takes <TT>start</TT> and <TT>end</TT> angles -that are measured in degrees counter-clockwise from 3 o'clock. If <TT> -end</TT> is less than <TT>start</TT> then it draws the arc in a -clockwise direction. + +<P>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 <TT>fl_arc()</TT>. <TT>x,y</TT> are the center of +the circle, and <TT>r</TT> is its radius. <TT>fl_arc()</TT> +takes <TT>start</TT> and <TT>end</TT> angles that are measured +in degrees counter-clockwise from 3 o'clock. If <TT>end</TT> is +less than <TT>start</TT> then it draws the arc in a clockwise +direction. + <H4>void fl_circle(float x, float y, float r)</H4> -<TT>fl_circle()</TT> is equivalent to <TT>fl_arc(...,0,360)</TT> 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 <TT>fl_arc()</TT> -. <I>This draws incorrectly if the transformation is both rotated and -non-square scaled.</I> -<H3><A name=text>Text</A></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. + +<P><TT>fl_circle()</TT> is equivalent to <TT>fl_arc(...,0,360)</TT> 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 <TT>fl_arc()</TT>. + +<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> +<TR> + <TD><B>Note:</B> + + <P><TT>fl_circle()</TT> draws incorrectly if the + transformation is both rotated and non-square scaled. + + </TD> +</TR> +</TABLE></CENTER> + +<H3><A name="text">Drawing Text</A></H3> + +<P>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. + <H4>void fl_draw(const char *, float x, float y) -<BR> void fl_draw(const char *, int n, float x, float y)</H4> - Draw a nul-terminated string or an array of <TT>n</TT> characters -starting at the given location. -<H4>void fl_draw(const char *, int x, int y, int w, int h, Fl_Align)</H4> - 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#Fl_Widget.align> -<TT>Fl_Widget::align()</TT></A> for values for <TT>align</TT>. The -value <TT>FL_ALIGN_INSIDE</TT> is ignored, as this function always -prints inside the box. -<H4>void fl_measure(const char *, int &w, int &h)</H4> - Measure how wide and tall the string will be when printed by the <TT> -fl_draw(...align)</TT> function. If the incoming <TT>w</TT> is -non-zero it will wrap to that width. +<BR>void fl_draw(const char *, int n, float x, float y)</H4> + +<P>Draw a nul-terminated string or an array of <TT>n</TT> characters +starting at the given location. + +<H4>void fl_draw(const char *, int x, int y, int w, int h, +Fl_Align align, Fl_Image *img = 0, int draw_symbols = 1)</H4> + +<P>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#Fl_Widget.align"><TT>Fl_Widget::align()</TT></A> +for values for <TT>align</TT>. The value +<TT>FL_ALIGN_INSIDE</TT> is ignored, as this function always +prints inside the box. + +<P>If <TT>img</TT> is provided and is not <TT>NULL</TT>, the +image is drawn above or below the text as specified by the +<TT>align</TT> value. + +<P>The <TT>draw_symbols</TT> argument specifies whether or not +to look for symbol names starting with the "@" character. + +<H4>void fl_measure(const char *, int &w, int &h, int draw_symbols = 1)</H4> + +<P>Measure how wide and tall the string will be when printed by +the <TT>fl_draw(...align)</TT> function. If the incoming +<TT>w</TT> is non-zero it will wrap to that width. + <H4>int fl_height()</H4> - Recommended minimum line spacing for the current font. You can also -just use the value of <TT>size</TT> passed to <A href=#fl_font><TT> -fl_font()</TT></A>. + +<P>Recommended minimum line spacing for the current font. You +can also just use the value of <TT>size</TT> passed to <A +href=#fl_font><TT>fl_font()</TT></A>. + <H4>int fl_descent()</H4> - Recommended distance above the bottom of a <TT>fl_height()</TT> tall -box to draw the text at so it looks centered vertically in that box. + +<P>Recommended distance above the bottom of a +<TT>fl_height()</TT> tall box to draw the text at so it looks +centered vertically in that box. + <H4>float fl_width(const char*) -<BR> float fl_width(const char*, int n) -<BR> float fl_width(uchar)</H4> - Return the pixel width of a nul-terminated string, a sequence of <TT>n</TT> - characters, or a single character in the current font. +<BR>float fl_width(const char*, int n) +<BR>float fl_width(uchar)</H4> + +<P>Return the pixel width of a nul-terminated string, a sequence of <TT>n</TT> +characters, or a single character in the current font. + <H4>const char *fl_shortcut_label(ulong)</H4> - Unparse a shortcut value as used by <A href=Fl_Button.html#Fl_Button.shortcut> -<TT>Fl_Button</TT></A> or <A href=Fl_Menu_Item.html#Fl_Menu_Item><TT> -Fl_Menu_Item</TT></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. -<H3><A name=fonts>Fonts</A></H3> -<H4><A name=fl_font>void fl_font(int face, int size)</A></H4> - 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 <TT> -fl_width()</TT>, but on X this will open the display. -<P>The font is identified by a <TT>face</TT> and a <TT>size</TT>. The -size of the font is measured in <TT>pixels</TT> (not "points"). Lines - should be spaced <TT>size</TT> pixels apart (or more). </P> -<P>The <TT>face</TT> is an index into an internal table. Initially -only the first 16 faces are filled in. There are symbolic names for -them: <TT>FL_HELVETICA</TT>, <TT>FL_TIMES</TT>, <TT>FL_COURIER</TT>, -and modifier values <TT>FL_BOLD</TT> and <TT>FL_ITALIC</TT> which can -be added to these, and <TT>FL_SYMBOL</TT> and <TT>FL_ZAPF_DINGBATS</TT> -. Faces greater than 255 cannot be used in <TT>Fl_Widget</TT> labels, -since it stores the index as a byte. </P> + +<P>Unparse a shortcut value as used by <A +href="Fl_Button.html#Fl_Button.shortcut"><TT>Fl_Button</TT></A> +or <A +href="Fl_Menu_Item.html#Fl_Menu_Item"><TT>Fl_Menu_Item</TT></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. + +<H3><A name="fonts">Fonts</A></H3> + +<P>FLTK supports a set of standard fonts based on the Times, +Helvetica/Arial, Courier, and Symbol typefaces, as well as +custom fonts that your application may load. Each font is +accessed by an index into a font table. + +<P>Initially only the first 16 faces are filled in. There are +symbolic names for them: <TT>FL_HELVETICA</TT>, +<TT>FL_TIMES</TT>, <TT>FL_COURIER</TT>, and modifier values +<TT>FL_BOLD</TT> and <TT>FL_ITALIC</TT> which can be added to +these, and <TT>FL_SYMBOL</TT> and <TT>FL_ZAPF_DINGBATS</TT>. +Faces greater than 255 cannot be used in <TT>Fl_Widget</TT> +labels, since <TT>Fl_Widget</TT> stores the index as a byte.</P> + +<H4><A name="fl_font">void fl_font(int face, int size)</A></H4> + +<P>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 <TT>fl_width()</TT>, but on X this will open +the display. + +<P>The font is identified by a <TT>face</TT> and a +<TT>size</TT>. The size of the font is measured in +<TT>pixels</TT> and not "points". Lines should be spaced +<TT>size</TT> pixels apart or more.</P> + <H4>int fl_font() -<BR> int fl_size()</H4> - Returns the face and size set by the most recent call to <TT> -fl_font(a,b)</TT>. This can be used to save/restore the font. -<H3><A name=overlay>Overlays</A></H3> -<H4>void fl_overlay_rect(int x, int y, int w, int h) -<BR> void fl_overlay_clear()</H4> - These functions allow you to draw interactive selection rectangles -without using the overlay hardware. 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 <TT> -fl_overlay_clear()</TT> will erase the rectangle without drawing a new -one. -<P>Using this is tricky. You should make a widget with both a <TT> -handle()</TT> and <TT>draw()</TT> method. <TT>draw()</TT> should call <TT> -fl_overlay_clear()</TT> before doing anything else. Your <TT>handle()</TT> - method should call <TT>window()->make_current()</TT> and then <TT> -fl_overlay_rect()</TT> after <TT>FL_DRAG</TT> events, and should call <TT> -fl_overlay_clear()</TT> after a <TT>FL_RELEASE</TT> event. </P> -<H2><A name=images>Images</A></H2> - To draw images, you can either do it directly from data in your -memory, or you can create <A href=#Fl_Bitmap><TT>Fl_Bitmap</TT></A>, <A href=#Fl_Image> -<TT>Fl_Image</TT></A>, or <A href=#Fl_Pixmap><TT>Fl_Pixmap</TT></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 is <I>much</I> faster. +<BR>int fl_size()</H4> + +<P>Returns the face and size set by the most recent call to +<TT>fl_font(a,b)</TT>. This can be used to save/restore the +font. + +<H3><A name="overlay">Drawing Overlays</A></H3> + +<P>These functions allow you to draw interactive selection rectangles +without using the overlay hardware. FLTK will XOR a single rectangle +outline over a window. + +<H4>void fl_overlay_rect(int x, int y, int w, int h); +<BR>void fl_overlay_clear();</H4> + +<P><TT>fl_overlay_rect()</TT> draws a selection rectangle, erasing any +previous rectangle by XOR'ing it first. <TT>fl_overlay_clear()</TT> +will erase the rectangle without drawing a new one. + +<P>Using these functions is tricky. You should make a widget +with both a <TT>handle()</TT> and <TT>draw()</TT> method. +<TT>draw()</TT> should call <TT>fl_overlay_clear()</TT> before +doing anything else. Your <TT>handle()</TT> method should call +<TT>window()->make_current()</TT> and then +<TT>fl_overlay_rect()</TT> after <TT>FL_DRAG</TT> events, and +should call <TT>fl_overlay_clear()</TT> after a +<TT>FL_RELEASE</TT> event.</P> + +<H2><A name="images">Drawing Images</A></H2> + +<P>To draw images, you can either do it directly from data in +your memory, or you can create a <A +href="#Fl_Image"><TT>Fl_Image</TT></A> object. 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 is <I>much</I> faster. + <H3>Direct Image Drawing</H3> - 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. -<H4><A NAME="fl_draw_image">void fl_draw_image(const uchar *, int X, int Y, int W, int H, int D + +<P>The behavior when drawing images when the current +transformation matrix is not the identity is not defined, so you +should only draw images when the matrix is set to the identity. + +<H4><A NAME="fl_draw_image">void fl_draw_image(const uchar *, int X, int Y, int W, int H, int D = 3, int LD = 0) -<BR> void fl_draw_image_mono(const uchar *, int X, int Y, int W, int H, +<BR>void fl_draw_image_mono(const uchar *, int X, int Y, int W, int H, int D = 1, int LD = 0)</A></H4> - Draw an 8-bit per color RGB or luminance image. The pointer points at -the "r" data of the top-left pixel. Data must be in <TT>r,g,b</TT> - order. <TT>X,Y</TT> are where to put the top-left corner. <TT>W</TT> - and <TT>H</TT> define the size of the image. <TT>D</TT> is the delta -to add to the pointer between pixels, it may be any value greater or -equal to <TT>3</TT>, or it can be negative to flip the image -horizontally. <TT>LD</TT> is the delta to add to the pointer between -lines (if 0 is passed it uses <TT>W * D</TT>), and may be larger than <TT> -W * D</TT> to crop data, or negative to flip the image vertically. -<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 to get rid + +<P>Draw an 8-bit per color RGB or luminance image. The pointer +points at the "r" data of the top-left pixel. Color +data must be in <TT>r,g,b</TT> order. <TT>X,Y</TT> are where to +put the top-left corner. <TT>W</TT> and <TT>H</TT> define the +size of the image. <TT>D</TT> is the delta to add to the pointer +between pixels, it may be any value greater or equal to +<TT>3</TT>, or it can be negative to flip the image +horizontally. <TT>LD</TT> is the delta to add to the pointer +between lines (if 0 is passed it uses <TT>W * D</TT>), and may +be larger than <TT>W * D</TT> to crop data, or negative to flip +the image vertically. + +<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 to get rid of the dithering if possible: </P> -<UL> -<PRE> + +<UL><PRE> Fl::visual(FL_RGB); -</PRE> -</UL> - Gray scale (1-channel) images may be drawn. This is done if <TT>abs(D)</TT> - is less than 3, or by calling <TT>fl_draw_image_mono()</TT>. 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 <TT>D</TT> 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. </P> -<H4>typedef void (*fl_draw_image_cb)(void *, int x, int y, int w, uchar +</PRE></UL> + +<P>Gray scale (1-channel) images may be drawn. This is done if +<TT>abs(D)</TT> is less than 3, or by calling +<TT>fl_draw_image_mono()</TT>. 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 +<TT>D</TT> greater than 1 will let you display one channel of a +color image. + +<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> +<TR> + <TD><B>Note:</B> + + <P>The X version does not support all possible visuals. + 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.</P> + + </TD> +</TR> +</TABLE></CENTER> + +<H4>typedef void (*fl_draw_image_cb)(void *, int x, int y, int w, uchar *) -<BR> void fl_draw_image(fl_draw_image_cb, void *, int X, int Y, int W, +<BR>void fl_draw_image(fl_draw_image_cb, void *, int X, int Y, int W, int H, int D = 3) -<BR> void fl_draw_image_mono(fl_draw_image_cb, void *, int X, int Y, +<BR>void fl_draw_image_mono(fl_draw_image_cb, void *, int X, int Y, int W, int H, int D = 1)</H4> - 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 <TT>void *</TT> user data pointer -(this can be used to point at a structure of information about the -image), and the <TT>x</TT>, <TT>y</TT>, and <TT>w</TT> of the scan line -desired from the image. 0,0 is the upper-left corner (<I>not <TT>X,Y</TT> -</I>). A pointer to a buffer to put the data into is passed. You must -copy <TT>w</TT> pixels from scanline <TT>y</TT>, starting at pixel <TT>x</TT> -, to this buffer. </P> -<P>Due to cropping, less than the whole image may be requested. So <TT> -x</TT> may be greater than zero, the first <TT>y</TT> may be greater -than zero, and <TT>w</TT> may be less than <TT>W</TT>. The buffer is -long enough to store the entire <TT>W * D</TT> 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 <TT> -x</TT> is not zero, copy the data over so the <TT>x</TT>'th pixel is at -the start of the buffer. </P> -<P>You can assume the <TT>y</TT>'s will be consecutive, except the -first one may be greater than zero. </P> -<P>If <TT>D</TT> is 4 or more, you must fill in the unused bytes with -zero. </P> + +<P>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 <TT>void *</TT> user data +pointer which can be used to point at a structure of information +about the image, and the <TT>x</TT>, <TT>y</TT>, and <TT>w</TT> +of the scan line desired from the image. 0,0 is the upper-left +corner of the image, <I>not <TT>X,Y</TT></I>. A pointer to a +buffer to put the data into is passed. You must copy <TT>w</TT> +pixels from scanline <TT>y</TT>, starting at pixel <TT>x</TT>, +to this buffer.</P> + +<P>Due to cropping, less than the whole image may be requested. +So <TT>x</TT> may be greater than zero, the first <TT>y</TT> may +be greater than zero, and <TT>w</TT> may be less than +<TT>W</TT>. The buffer is long enough to store the entire <TT>W +* D</TT> pixels, this is for convenience with some decompression +schemes where you must decompress the entire line at once: +decompress it into the buffer, and then if <TT>x</TT> is not +zero, copy the data over so the <TT>x</TT>'th pixel is at the +start of the buffer.</P> + +<P>You can assume the <TT>y</TT>'s will be consecutive, except +the first one may be greater than zero.</P> + +<P>If <TT>D</TT> is 4 or more, you must fill in the unused bytes +with zero.</P> + <H4>int fl_draw_pixmap(char **data, int X, int Y, Fl_Color = FL_GRAY)</H4> -Draws XPM image data, with the top-left corner at the given position. -The image 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: </P> -<UL> -<PRE> + +<P>Draws XPM image data, with the top-left corner at the given position. +The image 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:</P> + +<UL><PRE> #include "foo.xpm" ... fl_draw_pixmap(foo, X, Y); -</PRE> -</UL> - In the current version the XPM data is converted to 24-bit RGB color -and passed through <TT>fl_draw_image()</TT>. This is obviously not the -most efficient way to do it, and has the same visual limitations as -listed above for <TT>fl_draw_image()</TT>. Transparent colors are -replaced by the optional <TT>Fl_Color</TT> argument (this may change in -the future). +</PRE></UL> + +<P>Transparent colors are replaced by the optional +<TT>Fl_Color</TT> argument. To draw with true transparency you must +use the <A HREF="#Fl_Pixmap"><TT>Fl_Pixmap</TT></A> class. + <H4>int fl_measure_pixmap(char **data, int &w, int &h)</H4> - An XPM image contains the dimensions in its 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. -<H3><A name=Fl_Bitmap>class Fl_Bitmap</A></H3> - This object encapsulates the width, height, and bits of an X bitmap -(XBM), and allows you to make an <TT>Fl_Widget</TT> use a bitmap as a -label, or to just draw the bitmap directly. Under X it will create an -offscreen pixmap the first time it is drawn, and copy this each -subsequent time it is drawn. -<H4>Fl_Bitmap(const char *bits, int W, int H) -<BR> Fl_Bitmap(const uchar *bits, int W, int H)</H4> - Construct using an X bitmap. The bits pointer is simply copied to the -object, so it must point at persistent storage. The two constructors -are provided because various X implementations disagree about the type -of bitmap data. To use an XBM file use: + +<P>An XPM image contains the dimensions in its data. This +function finds and returns the width and height. The return +value is non-zero if the dimensions were parsed ok and zero if +there was any problem. + +<H3><A name="Fl_Image">Image Classes</A></H3> + +<P>FLTK provides a base image class called <A +HREF="Fl_Image.html"><TT>Fl_Image</TT></A> which supports +creating, copying, and drawing images of various kinds, along +with some basic color operations. Images can be used as labels +for widgets using the <A +HREF="Fl_Widget.html#Fl_Widget.image"><TT>image()</TT></A> and +<A +HREF="Fl_Widget.html#Fl_Widget.deimage"><TT>deimage()</TT></A> +methods or drawn directly. + +<P>The <TT>Fl_Image</TT> class +does almost nothing by itself, but is instead supported by three +basic image types: + <UL> -<PRE> -#include "foo.xbm" -... -Fl_Bitmap bitmap = new Fl_Bitmap(foo_bits, foo_width, foo_height); -</PRE> + + <LI><A HREF="Fl_Bitmap.html"><TT>Fl_Bitmap</TT></A></LI> + + <LI><A HREF="Fl_Pixmap.html"><TT>Fl_Pixmap</TT></A></LI> + + <LI><A HREF="Fl_RGB_Image.html"><TT>Fl_RGB_Image</TT></A></LI> + </UL> -<H4>~Fl_Bitmap()</H4> - The destructor will destroy any X pixmap created. It does not do -anything to the bits data. -<H4>void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)</H4> -<TT>x,y,w,h</TT> indicates a destination rectangle. <TT>ox,oy,w,h</TT> - 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. <TT>ox</TT> and <TT>oy</TT> may be negative and <TT>w</TT> and <TT> -h</TT> may be bigger than the bitmap) and this area is left unchanged. -<H4>void draw(int x, int y)</H4> - Draws the bitmap with the upper-left corner at <TT>x,y</TT>. This is -the same as doing <TT>draw(x,y,this->w,this->h,0,0)</TT>. -<H4>void label(Fl_Widget *)</H4> - Change the <TT>label()</TT> and the <TT>labeltype()</TT> of the widget -to draw the bitmap. 1 bits will be drawn with the <TT>labelcolor()</TT> -, zero bits will be unchanged. You can use the same bitmap for many -widgets. -<H2><A name=Fl_Pixmap>class Fl_Pixmap</A></H2> - This object encapsulates the data from an XPM image, and allows you to -make an <TT>Fl_Widget</TT> 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 24-bit RGB data -and uses <A href=#fl_draw_image><TT>fl_draw_image()</TT></A> to draw -it. Thus you will get dithered colors on an 8 bit screen. </P> -<H4>Fl_Pixmap(char *const* data)</H4> - Construct using XPM data. The data pointer is simply copied to the -object, so it must point at persistent storage. To use an XPM file do: + +<P>The <TT>Fl_Bitmap</TT> class encapsulates a mono-color bitmap image. +The <TT>draw()</TT> method draws the image using the current drawing +color. + +<P>The <TT>Fl_Pixmap</TT> class encapsulates a colormapped image. +The <TT>draw()</TT> method draws the image using the colors in the +file, and masks off any transparent colors automatically. + +<P>The <TT>Fl_RGB_Image</TT> class encapsulates a full-color (or +grayscale) image with 1 to 4 color components. Images with an +even number of components are assumed to contain an alpha +channel that is used for transparency. The transparency provided +by the <TT>draw()</TT> method is either a 24-bit blend against +the existing window contents or a "screen door" transparency +mask, depending on the platform and screen color depth. + +<P>FLTK also provides several image classes based on the three +standard image types for common file formats: + <UL> -<PRE> -#include <FL/Fl_Pixmap.H> -#include "foo.xpm" -... -Fl_Pixmap pixmap = new Fl_Pixmap(foo); -</PRE> + + <LI><A HREF="Fl_GIF_Image.html"><TT>Fl_GIF_Image</TT></A></LI> + + <LI><A HREF="Fl_JPEG_Image.html"><TT>Fl_JPEG_Image</TT></A></LI> + + <LI><A HREF="Fl_PNG_Image.html"><TT>Fl_PNG_Image</TT></A></LI> + + <LI><A HREF="Fl_PNM_Image.html"><TT>Fl_PNM_Image</TT></A></LI> + + <LI><A HREF="Fl_XBM_Image.html"><TT>Fl_XBM_Image</TT></A></LI> + + <LI><A HREF="Fl_XPM_Image.html"><TT>Fl_XPM_Image</TT></A></LI> + </UL> -<H4>~Fl_Pixmap()</H4> - The destructor will destroy any X pixmap created. It does not do -anything to the data. -<H4>void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)</H4> -<TT>x,y,w,h</TT> indicates a destination rectangle. <TT>ox,oy,w,h</TT> - is a source rectangle. This source rectangle is copied to the -destination. The source rectangle may extend outside the pixmap (i.e. <TT> -ox</TT> and <TT>oy</TT> may be negative and <TT>w</TT> and <TT>h</TT> - may be bigger than the pixmap) and this area is left unchanged. -<H4>void draw(int x, int y)</H4> - Draws the image with the upper-left corner at <TT>x,y</TT>. This is -the same as doing <TT>draw(x,y,this->w,this->h,0,0)</TT>. -<H4>void label(Fl_Widget *)</H4> - Change the <TT>label()</TT> and the <TT>labeltype()</TT> of the widget -to draw the pixmap. You can use the same pixmap for many widgets. -<H3><A name=Fl_Image>class Fl_Image</A></H3> - This object encapsulates a full-color RGB image, and allows you to -make an <TT>Fl_Widget</TT> use an 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>. -<H4>Fl_Image(const uchar *data, int W, int H, int D = 3, int LD = 0)</H4> - Construct using a pointer to RGB data. <TT>W</TT> and <TT>H</TT> are -the size of the image in pixels. <TT>D</TT> 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). <TT>LD</TT> is the delta between lines (it may -be more than <TT>D * W</TT> 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>~Fl_Image()</H4> - The destructor will destroy any X pixmap created. It does not do -anything to the data. -<H4>void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)</H4> -<TT>x,y,w,h</TT> indicates a destination rectangle. <TT>ox,oy,w,h</TT> - is a source rectangle. This source rectangle is copied to the -destination. The source rectangle may extend outside the image (i.e. <TT> -ox</TT> and <TT>oy</TT> may be negative and <TT>w</TT> and <TT>h</TT> - may be bigger than the image) and this area is left unchanged. + +<P>Each of these image classes load a named file of the +corresponding format. The <A +HREF="Fl_Shared_Image.html"><TT>Fl_Shared_Image</TT></A> class +can be used to load any type of image file - the class examines +the file and constructs an image of the appropriate type. + +<P>Finally, FLTK provides a special image class called <A +HREF="Fl_Tiled_Image.html"><TT>Fl_Tiled_Image</TT></A> to tile +another image object in the specified area. This class can be +used to tile a background image in a <TT>Fl_Group</TT> widget, +for example. + +<H4>virtual void copy();<BR> +virtual void copy(int w, int h);</H4> + +<P>The <TT>copy() method creates a copy of the image. The second form +specifies the new size of the image - the image is resized using the +nearest-neighbor algorithm. + +<H4>void draw(int x, int y, int w, int h, int ox = 0, int oy = 0);</H4> + +<P>The <TT>draw()</TT> method draws the image object. +<TT>x,y,w,h</TT> indicates a destination rectangle. +<TT>ox,oy,w,h</TT> is a source rectangle. This source rectangle +is copied to the destination. The source rectangle may extend +outside the image, i.e. <TT>ox</TT> and <TT>oy</TT> may be +negative and <TT>w</TT> and <TT>h</TT> may be bigger than the +image, and this area is left unchanged. + <H4>void draw(int x, int y)</H4> - Draws the image with the upper-left corner at <TT>x,y</TT>. This is -the same as doing <TT>draw(x,y,this->w,this->h,0,0)</TT>. -<H4>void label(Fl_Widget *)</H4> - Change the <TT>label()</TT> and the <TT>labeltype()</TT> of the widget -to draw the image. You can use the same image for many widgets. </BODY></HTML> + +<P>Draws the image with the upper-left corner at <TT>x,y</TT>. +This is the same as doing +<TT>draw(x,y,img->w(),img->h(),0,0)</TT>. + +</BODY> +</HTML> diff --git a/documentation/editor.html b/documentation/editor.html index 236bc8162..565ba5ee0 100644 --- a/documentation/editor.html +++ b/documentation/editor.html @@ -1,25 +1,35 @@ -<HTML><BODY> -<H1 ALIGN=RIGHT><A NAME=editor>4 - Designing a Simple Text Editor</A></H1> -This chapter takes you through the design of a simple FLTK-based text -editor. +<HTML> +<BODY> + +<H1 ALIGN="RIGHT"><A NAME="editor">4 - Designing a Simple Text Editor</A></H1> + +<P>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: + +<P>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>Menubar/menus for all functions. </LI> -<LI>Edit a single text file. </LI> -<LI>Load from a file. </LI> -<LI>Save to a file. </LI> -<LI>Cut/copy/delete/paste functions. </LI> -<LI>Search and replace functions. </LI> -<LI>Keep track of when the file has been changed. </LI> + + <LI>Provide a menubar/menus for all functions.</LI> + <LI>Edit a single text file, possibly with multiple views.</LI> + <LI>Load from a file.</LI> + <LI>Save to a file.</LI> + <LI>Cut/copy/delete/paste functions.</LI> + <LI>Search and replace functions.</LI> + <LI>Keep track of when the file has been changed.</LI> + </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> + +<P>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, which we'll place inside a class called <TT>EditorWindow</TT>: + +<UL><PRE> class EditorWindow : public Fl_Double_Window { public: EditorWindow(int w, int h, const char* t); @@ -35,29 +45,31 @@ class EditorWindow : public Fl_Double_Window { Fl_Text_Editor *editor; char search[256]; }; -</PRE> -</UL> +</PRE></UL> + <H2>Variables</H2> -Our text editor will need some global variables to keep track of -things: -<UL> -<PRE> -int changed = 0; -char filename[1024] = ""; -char search[256] = ""; -Fl_Text_Buffer *textbuf; -</PRE> -</UL> -The <TT>textbuf</TT> variable is the text editor buffer for our -window described previously. We'll cover the other variables as -we build the application. + +<P>Our text editor will need some global variables to keep track of +things: + +<UL><PRE> +int changed = 0; +char filename[256] = ""; +Fl_Text_Buffer *textbuf; +</PRE></UL> + +<P>The <TT>textbuf</TT> variable is the text editor buffer for +our window class described previously. We'll cover the other +variables as we build the application.</P> + <H2>Menubars 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.html#Fl_Menu_Item> -<TT>Fl_Menu_Item</TT></A> structure is used to define the menus and -items in a menubar: -<UL> -<PRE> + +<P>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.html"><TT>Fl_Menu_Item</TT></A> structure is +used to define the menus and items in a menubar:</P> + +<UL><PRE> Fl_Menu_Item menuitems[] = { { "&File", 0, 0, 0, FL_SUBMENU }, { "&New File", 0, (Fl_Callback *)new_cb }, @@ -87,237 +99,262 @@ Fl_Menu_Item menuitems[] = { { 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> +</PRE></UL> + +<P>Once we have the menus defined we can create the +<TT>Fl_Menu_Bar</TT> widget and assign the menus to it with:</P> + +<UL><PRE> Fl_Menu_Bar *m = new Fl_Menu_Bar(0, 0, 512, 30); m->copy(menuitems); -</PRE> -</UL> -We'll define the callback functions later. +</PRE></UL> + +<P>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_Text_Editor.html#Fl_Text_Editor"><TT>Fl_Text_Editor</TT></A> -widget to edit the text: -<UL> -<PRE> + +<P>To keep things simple our text editor will use the +<A HREF="Fl_Text_Editor.html"><TT>Fl_Text_Editor</TT></A> +widget to edit the text: + +<UL><PRE> w->editor = new Fl_Text_Editor(0, 30, 512, 354); w->editor->buffer(textbuf); -</PRE> -</UL> -So that we can keep track of changes to the file, we also want to add -a "modify" callback: -<UL> -<PRE> +</PRE></UL> + +<P>So that we can keep track of changes to the file, we also want to add +a "modify" callback:</P> + +<UL><PRE> textbuf->add_modify_callback(changed_cb, w); textbuf->call_modify_callbacks(); -</PRE> -</UL> -Finally, we want to use a mono-spaced font like <TT>FL_COURIER</TT>: -<UL> -<PRE> +</PRE></UL> + +<P>Finally, we want to use a mono-spaced font like <TT>FL_COURIER</TT>: + +<UL><PRE> w->editor->textfont(FL_COURIER); -</PRE> -</UL> +</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: -<P ALIGN=CENTER><IMG src="editor-replace.gif" ALT="The search and replace dialog."></P> -<UL> -<PRE> + +<P>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:</P> + +<P ALIGN="CENTER"><IMG src="editor-replace.gif" ALT="The search and replace dialog."><BR> +<I>Figure 4-1: The search and replace dialog.</I></P> + +<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> +</PRE></UL> + <H2>Callbacks</H2> -Now that we've defined the GUI components of our editor, we need to -define our callback functions. + +<P>Now that we've defined the GUI components of our editor, we +need to define our callback functions.</P> + <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); + +<P>This function will be called whenever the user changes any text in the +<TT>editor</TT> widget: + +<UL><PRE> +void changed_cb(int, int nInserted, int nDeleted,int, const char*, void* v) { + if ((nInserted || nDeleted) && !loading) changed = 1; + EditorWindow *w = (EditorWindow *)v; + set_title(w); + if (loading) w->editor->show_insert_position(); } -</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. +</PRE></UL> + +<P>The <TT>set_title()</TT> function is one that we will write to set +the changed status on the current file. We're doing it this way +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_.html#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(); + +<P>This callback function will call <A +href="Fl_Text_Editor.html#Fl_Text_Editor.kf_copy"><TT>kf_copy()</TT></A> +to copy the currently selected text to the clipboard:</P> + +<UL><PRE> +void copy_cb(Fl_Widget*, void* v) { + EditorWindow* e = (EditorWindow*)v; + Fl_Text_Editor::kf_copy(0, e->editor); } -</PRE> -</UL> +</PRE></UL> + <H3>cut_cb()</H3> - This callback function will call <A href=Fl_Input_.html#Fl_Input_.copy><TT> -input->copy()</TT></A> to copy the currently selected text to the -clipboard and then <A href=Fl_Input_.html#Fl_Input_.cut><TT>input->cut()</TT> -</A> to delete it: -<UL> -<PRE> -void cut_cb(void) { - input->copy(); - input->cut(); + +<P>This callback function will call <A +href="Fl_Text_Editor.html#Fl_Text_Editor.kf_cut"><TT>kf_cut()</TT></A> +to cut the currently selected text to the clipboard:</P> + +<UL><PRE> +void cut_cb(Fl_Widget*, void* v) { + EditorWindow* e = (EditorWindow*)v; + Fl_Text_Editor::kf_cut(0, e->editor); } -</PRE> -</UL> +</PRE></UL> + <H3>delete_cb()</H3> - This callback function will call <A href=Fl_Input_.html#Fl_Input_.cut><TT> -input->cut()</TT></A> to delete the selected text: -<UL> -<PRE> -void delete_cb(void) { - input->cut(); + +<P>This callback function will call <A +href="Fl_Text_Buffer.html#Fl_Text_Buffer.remove_selection"><TT>remove_selection()</TT></A> +to delete the currently selected text to the clipboard:</P> + +<UL><PRE> +void delete_cb(Fl_Widget*, void* v) { + textbuf->remove_selection(); } -</PRE> -</UL> +</PRE></UL> + <H3>find_cb()</H3> - This callback function asks for a search string using the <A href=functions.html#fl_input2> -<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) { + +<P>This callback function asks for a search string using the <A +href="functions.html#fl_input2"><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(Fl_Widget* w, void* v) { + EditorWindow* e = (EditorWindow*)v; const char *val; - val = fl_input("Search String:", search); + val = fl_input("Search String:", e->search); if (val != NULL) { // User entered a string - go find it! - strcpy(search, val); - find2_cb(); + strcpy(e->search, val); + find2_cb(w, v); } -} -</PRE> -</UL> +</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') { + +<P>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(Fl_Widget* w, void* v) { + EditorWindow* e = (EditorWindow*)v; + if (e->search[0] == '\0') { // Search string is blank; get a new one... - find_cb(); + find_cb(w, v); 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)); + int pos = e->editor->insert_position(); + int found = textbuf->search_forward(pos, e->search, &pos); + if (found) { + // Found a match; select and update the position... + textbuf->select(pos, pos+strlen(e->search)); + e->editor->insert_position(pos+strlen(e->search)); + e->editor->show_insert_position(); } - else fl_alert("No occurrences of \'%s\' found!", search); + else fl_alert("No occurrences of \'%s\' found!", e->search); } -</PRE> -</UL> - If the search string cannot be found we use the <A href="functions.html#fl_alert"><TT> -fl_alert()</TT></A> convenience function to display a message to that -effect. +</PRE></UL> + +<P>If the search string cannot be found we use the <A +href="functions.html#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; +<P>This callback function will clear the editor 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(Fl_Widget*, void*) { + if (!check_save()) return; filename[0] = '\0'; - input->value(""); - set_changed(0); + textbuf->select(0, textbuf->length()); + textbuf->remove_selection(); + changed = 0; + textbuf->call_modify_callbacks(); } -</PRE> -</UL> +</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; +<P>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(Fl_Widget*, void*) { + if (!check_save()) return; - newfile = fl_file_chooser("Open File?", "*", filename); - if (newfile != NULL) load_file(newfile); + char *newfile = fl_file_chooser("Open File?", "*", filename); + if (newfile != NULL) load_file(newfile, -1); } -</PRE> -</UL> - We call the <TT>load_file()</TT> function to actually load the file. +</PRE></UL> + +<P>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=functions.html#paste><TT>Fl::paste()</TT></A> - method: -<UL> -<PRE> -void paste_cb(void) { - Fl::paste(*input); + +<P>This callback function will call <A +href="Fl_Text_Editor.html#Fl_Text_Editor.kf_paste"><TT>kf_paste()</TT></A> +to paste the clipboard at the current position:</P> + +<UL><PRE> +void paste_cb(Fl_Widget*, void* v) { + EditorWindow* e = (EditorWindow*)v; + Fl_Text_Editor::kf_paste(0, e->editor); } -</PRE> -</UL> +</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(); + +<P>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 exits +from the program: + +<UL><PRE> +void quit_cb(Fl_Widget*, void*) { + if (changed && !check_save()) + return; + + exit(0); } -</PRE> -</UL> +</PRE></UL> + <H3>replace_cb()</H3> - The replace callback just shows the replace dialog: -<UL> -<PRE> + +<P>The replace callback just shows the replace dialog: + +<UL><PRE> void replace_cb(Fl_Widget*, void* v) { EditorWindow* e = (EditorWindow*)v; e->replace_dlg->show(); } -</PRE> -</UL> +</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> + +<P>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(Fl_Widget*, void* v) { EditorWindow* e = (EditorWindow*)v; const char *find = e->replace_find->value(); @@ -345,13 +382,14 @@ void replace2_cb(Fl_Widget*, void* v) { } else fl_alert("No occurrences of \'%s\' found!", find); } -</PRE> -</UL> +</PRE></UL> + <H3>replall_cb()</H3> -This callback will replace all occurences of the search string in the -file: -<UL> -<PRE> + +<P>This callback will replace all occurences of the search +string in the file: + +<UL><PRE> void replall_cb(Fl_Widget*, void* v) { EditorWindow* e = (EditorWindow*)v; const char *find = e->replace_find->value(); @@ -388,23 +426,25 @@ void replall_cb(Fl_Widget*, void* v) { if (times) fl_message("Replaced %d occurrences.", times); else fl_alert("No occurrences of \'%s\' found!", find); } -</PRE> -</UL> +</PRE></UL> + <H3>replcan_cb()</H3> -This callback just hides the replace dialog: -<UL> -<PRE> + +<P>This callback just hides the replace dialog: + +<UL><PRE> void replcan_cb(Fl_Widget*, void* v) { EditorWindow* e = (EditorWindow*)v; e->replace_dlg->hide(); } -</PRE> -</UL> +</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> + +<P>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! @@ -413,42 +453,38 @@ void save_cb(void) { } else save_file(filename); } -</PRE> -</UL> - The <TT>save_file()</TT> function saves the current file to the -specified filename. +</PRE></UL> + +<P>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> + +<P>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_.html#Fl_Input_.undo><TT> -undo()</TT></A> method: -<UL> -<PRE> -void undo_cb(void) { - input->undo(); -} -</PRE> -</UL> +</PRE></UL> + +<P>The <TT>save_file()</TT> function saves the current file to the +specified filename. + <H2>Other Functions</H2> - Now that we've defined the callback functions, we need our support -functions to make it all work: + +<P>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> + +<P>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; @@ -463,12 +499,13 @@ int check_save(void) { return (r == 2) ? 1 : 0; } -</PRE> -</UL> +</PRE></UL> + <H3>load_file()</H3> - This function loads the specified file into the <TT>input</TT> widget: -<UL> -<PRE> + +<P>This function loads the specified file into the <TT>textbuf</TT> class: + +<UL><PRE> int loading = 0; void load_file(char *newfile, int ipos) { loading = 1; @@ -485,15 +522,19 @@ void load_file(char *newfile, int ipos) { loading = 0; textbuf->call_modify_callbacks(); } -</PRE> -</UL> -When loading the file we use the -<A href="Fl_Text_Buffer.html#Fl_Text_Buffer.insertfile"><TT>loadfile()</TT></A> -method to "replace" the text in the buffer. +</PRE></UL> + +<P>When loading the file we use the <A +href="Fl_Text_Buffer.html#Fl_Text_Buffer.loadfile"><TT>loadfile()</TT></A> +method to "replace" the text in the buffer, or the <A +href="Fl_Text_Buffer.html#Fl_Text_Buffer.insertfile"><TT>insertfile()</TT></A> +method to insert text in the buffer from the named file. + <H3>save_file()</H3> -This function saves the current buffer to the specified file: -<UL> -<PRE> + +<P>This function saves the current buffer to the specified file: + +<UL><PRE> void save_file(char *newfile) { if (textbuf->savefile(newfile)) fl_alert("Error writing to file \'%s\':\n%s.", newfile, strerror(errno)); @@ -502,52 +543,60 @@ void save_file(char *newfile) { changed = 0; textbuf->call_modify_callbacks(); } -</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; +</PRE></UL> - if (filename[0] == '\0') strcpy(title, "Untitled"); - else { - slash = strrchr(filename, '/'); - if (slash == NULL) slash = strrchr(filename, '\\'); +<H3>set_title()</H3> - if (slash != NULL) strcpy(title, slash + 1); - else strcpy(title, filename); - } +<P>This function checks the <TT>changed</TT> variable and updates the +window label accordingly: +<UL><PRE> +void set_title(Fl_Window* w) { + if (filename[0] == '\0') strcpy(title, "Untitled"); + else { + char *slash; + slash = strrchr(filename, '/'); +#ifdef WIN32 + if (slash == NULL) slash = strrchr(filename, '\\'); +#endif + if (slash != NULL) strcpy(title, slash + 1); + else strcpy(title, filename); + } - if (changed) strcat(title, " (modified)"); + if (changed) strcat(title, " (modified)"); - window->label(title); - } + w->label(title); } -</PRE> -</UL> +</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> + +<P>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.html#basics>Chapter 1</A>, you may need to -include compiler and linker options to tell them where to find the FLTK +</PRE></UL> + +<P>or by using the <TT>fltk-config</TT> script with: + +<UL><PRE> +fltk-config --compile editor.cxx +</PRE></UL> + +<P>As noted in <A href="basics.html">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! </P> +or <TT>c++</TT> on your system. + +<P>Congratulations, you've just built your own text editor!</P> + <H2>The Final Product</H2> - The final editor window should look like the image on the next page. -<P ALIGN=CENTER><IMG src="editor.gif" ALT="The completed editor window."></P> -</BODY></HTML> + +The final editor window should look like the image in Figure 4-2. + +<P ALIGN="CENTER"><IMG src="editor.gif" ALT="The completed editor window."><BR> +<I>Figure 4-2: The completed editor window</I></P> + +</BODY> +</HTML> diff --git a/documentation/enumerations.html b/documentation/enumerations.html index 736090295..e9e67e002 100644 --- a/documentation/enumerations.html +++ b/documentation/enumerations.html @@ -1,22 +1,22 @@ <HTML><BODY> <H1 ALIGN=RIGHT><A NAME=Enumerations>C - FLTK Enumerations</A></H1> This appendix lists the enumerations provided in the <TT> -<FL/Enumerations.H></TT> header file, organized by section. +<FL/Enumerations.H></TT> header file, organized by section. Constants whose value is zero are marked with "(0)", this is often useful to know when programming. <H2>Version Numbers</H2> - The FLTK version number is stored in a number of compile-time -constants: + The FLTK version number is stored in a number of compile-time +constants: <UL> <LI><TT>FL_MAJOR_VERSION</TT> - The major release number, currently 1. </LI> <LI><TT>FL_MINOR_VERSION</TT> - The minor release number, currently 1. </LI> <LI><TT>FL_PATCH_VERSION</TT> - The patch release number, currently 0. </LI> -<LI><TT>FL_VERSION</TT> - A combined floating-point version number for +<LI><TT>FL_VERSION</TT> - A combined floating-point version number for the major, minor, and patch release numbers, currently 1.0100. </LI> </UL> <H2><A NAME="events">Events</A></H2> - Events are identified by an <TT>Fl_Event</TT> enumeration value. The -following events are currently defined: + Events are identified by an <TT>Fl_Event</TT> enumeration value. The +following events are currently defined: <UL> <LI><TT>FL_NO_EVENT</TT> - No event (or an event fltk does not understand) occurred (0).</LI> @@ -24,39 +24,39 @@ understand) occurred (0).</LI> <LI><TT>FL_RELEASE</TT> - A mouse button was released. </LI> <LI><TT>FL_ENTER</TT> - The mouse pointer entered a widget. </LI> <LI><TT>FL_LEAVE</TT> - The mouse pointer left a widget. </LI> -<LI><TT>FL_DRAG</TT> - The mouse pointer was moved with a button +<LI><TT>FL_DRAG</TT> - The mouse pointer was moved with a button pressed. </LI> <LI><TT>FL_FOCUS</TT> - A widget should receive keyboard focus. </LI> <LI><TT>FL_UNFOCUS</TT> - A widget loses keyboard focus. </LI> <LI><TT>FL_KEYBOARD</TT> - A key was pressed. </LI> <LI><TT>FL_CLOSE</TT> - A window was closed. </LI> -<LI><TT>FL_MOVE</TT> - The mouse pointer was moved with no buttons +<LI><TT>FL_MOVE</TT> - The mouse pointer was moved with no buttons pressed. </LI> <LI><TT>FL_SHORTCUT</TT> - The user pressed a shortcut key. </LI> <LI><TT>FL_DEACTIVATE</TT> - The widget has been deactivated. </LI> <LI><TT>FL_ACTIVATE</TT> - The widget has been activated. </LI> <LI><TT>FL_HIDE</TT> - The widget has been hidden. </LI> <LI><TT>FL_SHOW</TT> - The widget has been shown. </LI> -<LI><TT>FL_PASTE</TT> - The widget should paste the contents of the +<LI><TT>FL_PASTE</TT> - The widget should paste the contents of the clipboard. </LI> -<LI><TT>FL_SELECTIONCLEAR</TT> - The widget should clear any selections +<LI><TT>FL_SELECTIONCLEAR</TT> - The widget should clear any selections made for the clipboard. </LI> </UL> <H2><a name=when>Callback "When" Conditions</A></H2> - The following constants determine when a callback is performed: + The following constants determine when a callback is performed: <UL> <LI><TT>FL_WHEN_NEVER</TT> - Never call the callback (0). </LI> -<LI><TT>FL_WHEN_CHANGED</TT> - Do the callback only when the widget +<LI><TT>FL_WHEN_CHANGED</TT> - Do the callback only when the widget value changes. </LI> -<LI><TT>FL_WHEN_NOT_CHANGED</TT> - Do the callback whenever the user +<LI><TT>FL_WHEN_NOT_CHANGED</TT> - Do the callback whenever the user interacts with the widget. </LI> -<LI><TT>FL_WHEN_RELEASE</TT> - Do the callback when the button or key +<LI><TT>FL_WHEN_RELEASE</TT> - Do the callback when the button or key is released and the value changes. </LI> -<LI><TT>FL_WHEN_ENTER_KEY</TT> - Do the callback when the user presses +<LI><TT>FL_WHEN_ENTER_KEY</TT> - Do the callback when the user presses the ENTER key and the value changes. </LI> -<LI><TT>FL_WHEN_RELEASE_ALWAYS</TT> - Do the callback when the button +<LI><TT>FL_WHEN_RELEASE_ALWAYS</TT> - Do the callback when the button or key is released, even if the value doesn't change. </LI> -<LI><TT>FL_WHEN_ENTER_KEY_ALWAYS</TT> - Do the callback when the user +<LI><TT>FL_WHEN_ENTER_KEY_ALWAYS</TT> - Do the callback when the user presses the ENTER key, even if the value doesn't change. </LI> </UL> <H2><A NAME="button_values">Fl::event_button() Values</A></H2> @@ -72,7 +72,7 @@ is released and the value changes. </LI> <H2><A NAME="key_values">Fl::event_key() Values</A></H2> The following constants define the non-ASCII keys on the keyboard for <TT> -FL_KEYBOARD</TT> and <TT>FL_SHORTCUT</TT> events: +FL_KEYBOARD</TT> and <TT>FL_SHORTCUT</TT> events: <UL> <LI><TT>FL_Button</TT> - A mouse button; use <TT>Fl_Button + n</TT> for mouse button <TT>n</TT>. </LI> @@ -112,7 +112,7 @@ FL_KEYBOARD</TT> and <TT>FL_SHORTCUT</TT> events: </UL> <H2>Fl::event_state() Values</H2> The following constants define bits in the <TT>Fl::event_state()</TT> - value: + value: <UL> <LI><TT>FL_SHIFT</TT> - One of the shift keys is down. </LI> <LI><TT>FL_CAPS_LOCK</TT> - The caps lock is on. </LI> @@ -127,8 +127,8 @@ FL_KEYBOARD</TT> and <TT>FL_SHORTCUT</TT> events: </UL> <H2><a name=align>Alignment Values</A></H2> The following constants define bits that can be used with <A href=Fl_Widget.html#Fl_Widget.align> -<TT>Fl_Widget::align()</TT></A> to control the positioning of the -label: +<TT>Fl_Widget::align()</TT></A> to control the positioning of the +label: <UL> <LI><TT>FL_ALIGN_CENTER</TT> - The label is centered (0). </LI> <LI><TT>FL_ALIGN_TOP</TT> - The label is top-aligned. </LI> @@ -150,12 +150,12 @@ label inside the widget. </LI> </UL> <H2><a name=fonts>Fonts</A></H2> - The following constants define the standard FLTK fonts: + The following constants define the standard FLTK fonts: <ul> <LI><TT>FL_HELVETICA</TT> - Helvetica (or Arial) normal (0). </LI> <LI><TT>FL_HELVETICA_BOLD</TT> - Helvetica (or Arial) bold. </LI> <LI><TT>FL_HELVETICA_ITALIC</TT> - Helvetica (or Arial) oblique. </LI> -<LI><TT>FL_HELVETICA_BOLD_ITALIC</TT> - Helvetica (or Arial) +<LI><TT>FL_HELVETICA_BOLD_ITALIC</TT> - Helvetica (or Arial) bold-oblique. </LI> <LI><TT>FL_COURIER</TT> - Courier normal. </LI> <LI><TT>FL_COURIER_BOLD</TT> - Courier bold. </LI> @@ -168,12 +168,12 @@ bold-oblique. </LI> <LI><TT>FL_SYMBOL</TT> - Standard symbol font. </LI> <LI><TT>FL_SCREEN</TT> - Default monospaced screen font. </LI> <LI><TT>FL_SCREEN_BOLD</TT> - Default monospaced bold screen font. </LI> -<LI><TT>FL_ZAPF_DINGBATS</TT> - Zapf-dingbats font. +<LI><TT>FL_ZAPF_DINGBATS</TT> - Zapf-dingbats font. </ul> <H2><a name=colors>Colors</A></H2> - The following color constants can be used to access the colors in the -FLTK standard color palette: + The following color constants can be used to access the colors in the +FLTK standard color palette: <UL> <LI><TT>FL_BLACK</TT> - the default label color (0)</LI> <LI><TT>FL_RED</TT></LI> @@ -209,9 +209,9 @@ B*FL_NUM_BLUE/256);</tt> <H2><a name=cursor>Cursors</A></H2> -<P>The following constants define the mouse cursors that are available in -FLTK. The double-headed arrows are bitmaps -provided by FLTK on X, the others are provided by system-defined +<P>The following constants define the mouse cursors that are available in +FLTK. The double-headed arrows are bitmaps +provided by FLTK on X, the others are provided by system-defined cursors.</P> <UL> <LI><TT>FL_CURSOR_DEFAULT</TT> - the default cursor, usually an arrow (0)</LI> @@ -230,19 +230,19 @@ cursors.</P> </UL> <H2>FD "When" Conditions</H2> <UL> -<LI><TT>FL_READ</TT> - Call the callback when there is data to be +<LI><TT>FL_READ</TT> - Call the callback when there is data to be read. </LI> -<LI><TT>FL_WRITE</TT> - Call the callback when data can be written +<LI><TT>FL_WRITE</TT> - Call the callback when data can be written without blocking. </LI> -<LI><TT>FL_EXCEPT</TT> - Call the callback if an exception occurs on +<LI><TT>FL_EXCEPT</TT> - Call the callback if an exception occurs on the file. </LI> </UL> <H2><a name=damage>Damage Masks</A></H2> - The following damage mask bits are used by the standard FLTK widgets: + The following damage mask bits are used by the standard FLTK widgets: <UL> <LI><TT>FL_DAMAGE_CHILD</TT> - A child needs to be redrawn. </LI> <LI><TT>FL_DAMAGE_EXPOSE</TT> - The window was exposed. </LI> -<LI><TT>FL_DAMAGE_SCROLL</TT> - The <TT>Fl_Scroll</TT> widget was +<LI><TT>FL_DAMAGE_SCROLL</TT> - The <TT>Fl_Scroll</TT> widget was scrolled. </LI> <LI><TT>FL_DAMAGE_OVERLAY</TT> - The overlay planes need to be redrawn. </LI> <LI><TT>FL_DAMAGE_ALL</TT> - Everything needs to be redrawn. </LI> diff --git a/documentation/events.html b/documentation/events.html index 2eb847545..a742d69f4 100644 --- a/documentation/events.html +++ b/documentation/events.html @@ -1,238 +1,336 @@ -<HTML><BODY> -<H1 ALIGN=RIGHT><A NAME=events>6 - Handling Events</A></H1> - This chapter discusses the FLTK event model and how to handle events -in your program or widget. +<HTML> +<BODY> + +<H1 ALIGN="RIGHT"><A NAME="events">6 - Handling Events</A></H1> + +<P>This chapter discusses the FLTK event model and how to handle +events in your program or widget. + <H2>The FLTK Event Model</H2> -<P>Every time a user moves the mouse pointer, clicks a button, or presses -a key, an event is generated and sent to your application. Events can also -come from other programs like the window manager. +<P>Every time a user moves the mouse pointer, clicks a button, +or presses a key, an event is generated and sent to your +application. Events can also come from other programs like the +window manager. <P>Events are identified by the integer argument passed to the -<A href="subclassing.html#handle"> <TT>Fl_Widget::handle()</TT></A> virtual -method. Other information about the most recent event is stored in +<A href="subclassing.html#handle"><TT>Fl_Widget::handle()</TT></A> virtual +method. Other information about the most recent event is stored in static locations and acquired by calling the <A -href=#event_xxx><TT>Fl::event_*()</TT></A> methods. This static -information remains valid until the next event is read from window -system (i.e. it is ok to look at it outside of the <TT>handle()</TT> -method). +href="#event_xxx"><TT>Fl::event_*()</TT></A> methods. This static +information remains valid until the next event is read from the window +system, so it is ok to look at it outside of the <TT>handle()</TT> +method. <H2>Mouse Events</H2> + <H3>FL_PUSH</H3> -A mouse button has gone down with the mouse pointing at this widget. -You can find out what button by calling <A href="functions.html#event_button"><TT> -Fl::event_button()</TT></A>. You find out the mouse position by -calling <A href="functions.html#event_x"><TT>Fl::event_x()</TT></A> and <A href="functions.html#event_y"> -<TT>Fl::event_y()</TT></A>. -<P>A widget indicates that it "wants" the mouse click by returning -non-zero from its <A href="subclassing.html#handle"><TT>handle()</TT></A> - method. It will then become the <A href="functions.html#pushed"><TT> -Fl::pushed()</TT></A> widget and will get <TT>FL_DRAG</TT> and the -matching <TT>FL_RELEASE</TT> events. If <TT>handle()</TT> returns zero -then FLTK will try sending the <TT>FL_PUSH</TT> to another widget. </P> + +<P>A mouse button has gone down with the mouse pointing at this +widget. You can find out what button by calling <A +href="Fl.html#Fl.event_button"><TT> +Fl::event_button()</TT></A>. You find out the mouse position by +calling <A +href="Fl.html#Fl.event_x"><TT>Fl::event_x()</TT></A> and <A +href="Fl.html#Fl.event_y"> <TT>Fl::event_y()</TT></A>. + +<P>A widget indicates that it "wants" the mouse click +by returning non-zero from its <A +href="subclassing.html#handle"><TT>handle()</TT></A> method. It +will then become the <A href="Fl.html#Fl.pushed"><TT> +Fl::pushed()</TT></A> widget and will get <TT>FL_DRAG</TT> and +the matching <TT>FL_RELEASE</TT> events. If <TT>handle()</TT> +returns zero then FLTK will try sending the <TT>FL_PUSH</TT> to +another widget. </P> + <H3>FL_DRAG</H3> -The mouse has moved with a button held down. The current button state is -in <a href="functions.html#event_state"><tt>Fl::event_state()</tt></a>. The mouse position -is in <a href="functions.html#event_x"><tt>Fl::event_x()</tt></a> and -<a href="functions.html#event_y"><tt>Fl::event_y()</tt></a>. + +<P>The mouse has moved with a button held down. The current +button state is in <a +href="Fl.html#Fl.event_state"><tt>Fl::event_state()</tt></a>. +The mouse position is in <a +href="Fl.html#Fl.event_x"><tt>Fl::event_x()</tt></a> and <a +href="Fl.html#Fl.event_y"><tt>Fl::event_y()</tt></a>. <P>To receive <CODE>FL_DRAG</CODE> events you must also respond to the <CODE>FL_PUSH</CODE> and <CODE>FL_RELEASE</CODE> events. <H3>FL_RELEASE</H3> - A mouse button has been released. You can find out what button by -calling <A href="functions.html#event_button"><TT>Fl::event_button()</TT></A>. + +<P>A mouse button has been released. You can find out what +button by calling <A +href="Fl.html#Fl.event_button"><TT>Fl::event_button()</TT></A>. + <H3>FL_MOVE</H3> - The mouse has moved without any mouse buttons held down. This event -is sent to the <A href="functions.html#belowmouse"><TT>Fl::belowmouse()</TT></A> + +<P>The mouse has moved without any mouse buttons held down. +This event is sent to the <A +href="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse()</TT></A> widget. + +<H3>FL_MOUSEWHEEL</H3> + +<P>The user has moved the mouse wheel. The <A +HREF="Fl.html#Fl.event_dx"><TT>Fl::event_dx()</TT></A> and <A +HREF="Fl.html#Fl.event_dy"><TT>Fl::event_dy()</TT></A> methods +can be used to find the amount to scroll horizontally and +vertically. + <H2>Focus Events</H2> + <H3>FL_ENTER</H3> - 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 its <A href=functions.html#handle> -<TT>handle()</TT></A> method. It then becomes the <A href=functions.html#belowmouse> -<TT>Fl::belowmouse()</TT></A> widget and will receive <TT>FL_MOVE</TT> - and <TT>FL_LEAVE</TT> events. + +<P>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 its <A +href="Fl.html#Fl.handle"><TT>handle()</TT></A> method. It then +becomes the <A +href="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse()</TT></A> +widget and will receive <TT>FL_MOVE</TT> and <TT>FL_LEAVE</TT> +events. + <H3>FL_LEAVE</H3> - The mouse has moved out of the widget. + +<P>The mouse has moved out of the widget. + <H3>FL_FOCUS</H3> - 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 its <A href=functions.html#handle> -<TT>handle()</TT></A> method. It then becomes the <A href=functions.html#focus> -<TT>Fl::focus()</TT></A> widget and gets <TT>FL_KEYBOARD</TT> and <TT> -FL_UNFOCUS</TT> events. </P> -<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=functions.html#event_key> -<TT>Fl::event_key()</TT></A> to figure out why it moved. For -navigation it will be the key pressed and for instructions from the -window manager it will be zero. </P> + +<P>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 +its <A +href="Fl_Widget.html#Fl_Widget.handle"><TT>handle()</TT></A> +method. It then becomes the <A +href="Fl.html#Fl.focus"><TT>Fl::focus()</TT></A> widget and gets +<TT>FL_KEYDOWN</TT>, <TT>FL_KEYUP</TT>, and <TT>FL_UNFOCUS</TT> +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="Fl.html#Fl.event_key"><TT>Fl::event_key()</TT></A> to +figure out why it moved. For navigation it will be the key +pressed and interaction with the window manager it will be +zero. + <H3>FL_UNFOCUS</H3> -Sent to the previous <A href=functions.html#focus><TT>Fl::focus()</TT></A> -widget when another widget gets the focus. + +<P>This event is sent to the previous <A +href="Fl.html#Fl.focus"><TT>Fl::focus()</TT></A> widget when +another widget gets the focus or the window loses focus. + <H2>Keyboard Events</H2> -<H3>FL_KEYBOARD</H3> - A key press. The key pressed can be found in <A href=functions.html#event_key> -<TT>Fl::event_key()</TT></A>. The text that the key should insert can -be found with <A href=functions.html#event_text><TT>Fl::event_text()</TT> -</A> and its length is in <A href=functions.html#event_length><TT> -Fl::event_length()</TT></A>. If you use the key <TT>handle()</TT> -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 <TT>FL_SHORTCUT</TT> -event. - -<P>To receive <CODE>FL_KEYBOARD</CODE> events you must also respond to the -<CODE>FL_FOCUS</CODE> and <CODE>FL_UNFOCUS</CODE> events. - -<p>If you are writing a text-editing widget you may also want to call -the <a href=#compose>Fl::compose()</a> function to translate -individual keystrokes into foreign characters. + +<H3>FL_KEYDOWN, FL_KEYUP</H3> + +<P>A key was pressed or released. The key can be found in <A +href="Fl.html#Fl.event_key"><TT>Fl::event_key()</TT></A>. The +text that the key should insert can be found with <A +href="Fl.html#Fl.event_text"><TT>Fl::event_text()</TT></A> and +its length is in <A +href="Fl.html#Fl.event_length"><TT>Fl::event_length()</TT></A>. +If you use the key <TT>handle()</TT> should return 1. If you +return zero then FLTK assumes you ignored the key and will +then attempt to send it to a parent widget. If none of them want +it, it will change the event into a <TT>FL_SHORTCUT</TT> event. + +<P>To receive <CODE>FL_KEYBOARD</CODE> events you must also +respond to the <CODE>FL_FOCUS</CODE> and <CODE>FL_UNFOCUS</CODE> +events. + +<P>If you are writing a text-editing widget you may also want to +call the <a href="Fl.html#Fl.compose"><TT>Fl::compose()</TT></a> +function to translate individual keystrokes into foreign +characters. <H3>FL_SHORTCUT</H3> -If the <A href=functions.html#focus><TT>Fl::focus()</TT></A> widget is zero -or ignores an <TT>FL_KEYBOARD</TT> event then FLTK tries sending this -event to every widget it can, until one of them returns non-zero. <TT> -FL_SHORTCUT</TT> is first sent to the <TT>belowmouse()</TT> widget, -then its parents and siblings, and eventually to every widget in the -window, trying to find an object that returns non-zero. FLTK tries -really hard to not to ignore any keystrokes! -<P>You can also make "global" shortcuts by using <A href=osissues.html#add_handler> -<TT>Fl::add_handler()</TT></A>. A global shortcut will work no matter -what windows are displayed or which one has the focus. </P> + +<P>If the <A href="Fl.html#Fl.focus"><TT>Fl::focus()</TT></A> +widget is zero or ignores an <TT>FL_KEYBOARD</TT> event then +FLTK tries sending this event to every widget it can, until one +of them returns non-zero. <TT>FL_SHORTCUT</TT> is first sent to +the <TT>Fl::belowmouse()</TT> widget, then its parents and +siblings, and eventually to every widget in the window, trying +to find an object that returns non-zero. FLTK tries really hard +to not to ignore any keystrokes! + +<P>You can also make "global" shortcuts by using <A +href="Fl.html#Fl.add_handler"><TT>Fl::add_handler()</TT></A>. A +global shortcut will work no matter what windows are displayed +or which one has the focus.</P> + <H2>Widget Events</H2> + <H3>FL_DEACTIVATE</H3> - This widget is no longer active, due to <A href=Fl_Widget.html#Fl_Widget.deactivate> -<TT>deactivate()</TT></A> being called on it or one of its parents. <TT> -active()</TT> may still be true after this, the widget is only active -if <TT>active()</TT> is true on it and all its parents (use <TT> -active_r()</TT> to check this). + +<P>This widget is no longer active, due to <A +href="Fl_Widget.html#Fl_Widget.deactivate"><TT>deactivate()</TT></A> +being called on it or one of its parents. <TT> active()</TT> may +still be true after this, the widget is only active if +<TT>active()</TT> is true on it and all its parents (use <TT>active_r()</TT> to check this). + <H3>FL_ACTIVATE</H3> - This widget is now active, due to <A href=Fl_Widget.html#Fl_Widget.activate> -<TT>activate()</TT></A> being called on it or one of its parents. + +<P>This widget is now active, due to <A +href="Fl_Widget.html#Fl_Widget.activate"><TT>activate()</TT></A> +being called on it or one of its parents. + <H3>FL_HIDE</H3> - This widget is no longer visible, due to <A href=Fl_Widget.html#Fl_Widget.hide><tt>hide()</tt></a> being called on it or one of its -parents, or due to a parent window being minimized. <tt>visible()</tt> -may still be true after this, but the widget is visible only if -<tt>visible()</tt> is true for it and all its parents (use -<tt>visible_r()</tt> to check this). +<P>This widget is no longer visible, due to <A +href="Fl_Widget.html#Fl_Widget.hide"><tt>hide()</tt></a> being +called on it or one of its parents, or due to a parent window +being minimized. <tt>visible()</tt> may still be true after +this, but the widget is visible only if <tt>visible()</tt> is +true for it and all its parents (use <tt>visible_r()</tt> to +check this). <h3>FL_SHOW</h3> -This widget is visible again, due to <a -href=Fl_Widget.html#Fl_Widget.show> -<TT>show()</TT></A> being called on it or one of its parents, or due to -a parent window being restored. <I>Child <TT>Fl_Window</TT>s respond to -this by actually creating the window if not done already, so if you -subclass a window, be sure to pass <TT>FL_SHOW</TT> to the base class <TT> -handle()</TT> method!</I> +<P>This widget is visible again, due to <a +href="Fl_Widget.html#Fl_Widget.show"><TT>show()</TT></A> being +called on it or one of its parents, or due to a parent window +being restored. <I>Child <TT>Fl_Window</TT>s respond to this by +actually creating the window if not done already, so if you +subclass a window, be sure to pass <TT>FL_SHOW</TT> to the base +class <TT>handle()</TT> method!</I> + <H2>Clipboard Events</H2> + <H3>FL_PASTE</H3> - You should get this event some time after you call <A href=functions.html#paste> -<TT>Fl::paste()</TT></A>. The contents of <A href=functions.html#event_text> -<TT>Fl::event_text()</TT></A> is the text to insert and the number of -characters is in <A href=functions.html#event_length><TT> -Fl::event_length()</TT></A>. + +<P>You should get this event some time after you call <A +href="Fl.html#Fl.paste"><TT>Fl::paste()</TT></A>. The contents +of <A href="Fl.html#Fl.event_text"><TT>Fl::event_text()</TT></A> +is the text to insert and the number of characters is in <A +href="Fl.html#Fl.event_length"><TT>Fl::event_length()</TT></A>. + <H3>FL_SELECTIONCLEAR</H3> - The <A href=functions.html#selection_owner>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. Motif programs used this to clear the selection -indication. Most modern programs ignore this. -<H2><A name=event_xxx>Fl::event_*() methods</A></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 <TT>handle()</TT> and <TT>callback()</TT> - methods. + +<P>The <A +href="Fl.html#Fl.selection_owner"><TT>Fl::selection_owner()</TT></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. Motif programs used this to clear the +selection indication. Most modern programs ignore this. + +<H2><A name="event_xxx">Fl::event_*() methods</A></H2> + +<P>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 <TT>handle()</TT> and +<TT>callback()</TT> methods. + <P>These are all trivial inline functions and thus very fast and small: </P> + <UL> -<LI><A href=functions.html#event_button><TT>Fl::event_button</TT></A></LI> -<LI><A href=functions.html#event_clicks><TT>Fl::event_clicks</TT></A></LI> -<LI><A href=functions.html#event_inside><TT>Fl::event_inside</TT></A></LI> -<LI><A href=functions.html#event_is_click><TT>Fl::event_is_click</TT></A></LI> -<LI><A href=functions.html#event_key><TT>Fl::event_key</TT></A></LI> -<LI><A href=functions.html#event_length><TT>Fl::event_length</TT></A></LI> -<LI><A href=functions.html#event_state><TT>Fl::event_state</TT></A></LI> -<LI><A href=functions.html#event_text><TT>Fl::event_text</TT></A></LI> -<LI><A href=functions.html#event_x><TT>Fl::event_x</TT></A></LI> -<LI><A href=functions.html#event_x_root><TT>Fl::event_x_root</TT></A></LI> -<LI><A href=functions.html#event_y><TT>Fl::event_y</TT></A></LI> -<LI><A href=functions.html#event_y_root><TT>Fl::event_y_root</TT></A></LI> -<LI><A href=functions.html#get_key><TT>Fl::get_key</TT></A></LI> -<LI><A href=functions.html#get_mouse><TT>Fl::get_mouse</TT></A></LI> -<LI><A href=functions.html#test_shortcut><TT>Fl::test_shortcut</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.event_button"><TT>Fl::event_button</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.event_clicks"><TT>Fl::event_clicks</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.event_dx"><TT>Fl::event_dx</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.event_dy"><TT>Fl::event_dy</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.event_inside"><TT>Fl::event_inside</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.event_is_click"><TT>Fl::event_is_click</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.event_key"><TT>Fl::event_key</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.event_length"><TT>Fl::event_length</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.event_state"><TT>Fl::event_state</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.event_text"><TT>Fl::event_text</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.event_x"><TT>Fl::event_x</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.event_x_root"><TT>Fl::event_x_root</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.event_y"><TT>Fl::event_y</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.event_y_root"><TT>Fl::event_y_root</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.get_key"><TT>Fl::get_key</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.get_mouse"><TT>Fl::get_mouse</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.test_shortcut"><TT>Fl::test_shortcut</TT></A></LI> + </UL> + <H2><A name=propagation>Event Propagation</A></H2> - FLTK follows very simple and unchangeable rules for sending events. -The major innovation is that widgets can indicate (by returning 0 from -the <TT>handle()</TT> 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 toolkits. -<P>Most events are sent directly to the <TT>handle()</TT> method of the <TT> -Fl_Window</TT> that the window system says they belong to. The window -(actually the <TT>Fl_Group</TT> that <TT>Fl_Window</TT> is a subclass -of) is responsible for sending the events on to any child widgets. To -make the <TT>Fl_Group</TT> code somewhat easier, FLTK sends some events -(<TT>FL_DRAG</TT>, <TT>FL_RELEASE</TT>, <TT>FL_KEYBOARD</TT>, <TT> -FL_SHORTCUT</TT>, <TT>FL_UNFOCUS</TT>, and <TT>FL_LEAVE</TT>) directly -to leaf widgets. These procedures control those leaf widgets: </P> + +<P>FLTK follows very simple and unchangeable rules for sending +events. The major innovation is that widgets can indicate (by +returning 0 from the <TT>handle()</TT> 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 toolkits. + +<P>Most events are sent directly to the <TT>handle()</TT> method +of the <TT>Fl_Window</TT> that the window system says they +belong to. The window (actually the <TT>Fl_Group</TT> that +<TT>Fl_Window</TT> is a subclass of) is responsible for sending +the events on to any child widgets. To make the +<TT>Fl_Group</TT> code somewhat easier, FLTK sends some events +(<TT>FL_DRAG</TT>, <TT>FL_RELEASE</TT>, <TT>FL_KEYBOARD</TT>, +<TT>FL_SHORTCUT</TT>, <TT>FL_UNFOCUS</TT>, and +<TT>FL_LEAVE</TT>) directly to leaf widgets. These procedures +control those leaf widgets: + <UL> -<LI><A href=osissues.html#add_handler><TT>Fl::add_handler</TT></A></LI> -<LI><A href=functions.html#belowmouse><TT>Fl::belowmouse</TT></A></LI> -<LI><A href=functions.html#focus><TT>Fl::focus</TT></A></LI> -<LI><A href=functions.html#grab><TT>Fl::grab</TT></A></LI> -<LI><A href=functions.html#modal><TT>Fl::modal</TT></A></LI> -<LI><A href=functions.html#pushed><TT>Fl::pushed</TT></A></LI> -<LI><TT>Fl::release</TT></LI> -<LI><A href=Fl_Widget.html#Fl_Widget.take_focus><TT>Fl_Widget::take_focus</TT></A> -</LI> + + <LI><A HREF="Fl.html#Fl.add_handler"><TT>Fl::add_handler</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.focus"><TT>Fl::focus</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.grab"><TT>Fl::grab</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.modal"><TT>Fl::modal</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.pushed"><TT>Fl::pushed</TT></A></LI> + + <LI><A HREF="Fl.html#Fl.release"><TT>Fl::release</TT></A></LI> + + <LI><A HREF="Fl_Widget.html#Fl_Widget.take_focus"><TT>Fl_Widget::take_focus</TT></A></LI> + </UL> -<H2><A name=compose>FLTK Compose-Character Sequences</A></H2> +<H2><A name="compose">FLTK Compose-Character Sequences</A></H2> -The foreign-letter compose processing done by the <A -href=Fl_Input.html#compose><tt>Fl_Input</tt></a> widget is provided in +<P>The foreign-letter compose processing done by the <A +href="Fl_Input.html#compose"><tt>Fl_Input</tt></a> widget is provided in a function that you can call if you are writing your own text editor widget. -<p>Fltk uses it's own compose processing to allow "preview" of the -partially composed sequence, which is impossible with the usual -"dead key" processing. - -<p>Although currently only characters in the ISO-8859-1 character set are -handled, you should call this in case any enhancements to the -processing are done in the future. The interface has been designed to -handle arbitrary UTF-8 encoded text. - -<h4><tt>int Fl::compose(int& del)</tt></h4> +<p>FLTK uses its own compose processing to allow "preview" of +the partially composed sequence, which is impossible with the +usual "dead key" processing. -<p>Use of this function is very simple. Any text editing widget should -call this for each <tt>FL_KEYBOARD</tt> event. +<p>Although currently only characters in the ISO-8859-1 +character set are handled, you should call this in case any +enhancements to the processing are done in the future. The +interface has been designed to handle arbitrary UTF-8 encoded +text. -<p>If <i>true</i> is returned, then it has modified the -Fl::event_text() and Fl::event_length() to a set of <i>bytes</i> to -insert (it may be of zero length!). In will also set the "del" -parameter to the number of <i>bytes</i> to the left of the cursor to -delete, this is used to delete the results of the previous call to -Fl::compose(). +<P>The following methods are provided for character composition: -<p>If <i>false</i> is returned, the keys should be treated as function -keys, and del is set to zero. You could insert the text anyways, if -you don't know what else to do. +<UL> -<p>Though the current implementation returns immediately, future -versions may take quite awhile, as they may pop up a window or do -other user-interface things to allow characters to be selected. + <LI><A HREF="Fl.html#Fl.compose"><TT>Fl::compose()</TT></A></LI> -<h4><tt>int Fl::compose_reset()</tt></h4> + <LI><A HREF="Fl.html#Fl.compose_reset"><TT>Fl::compose_reset()</TT></A></LI> -<p>If the user moves the cursor, be sure to call Fl::compose_reset(). -The next call to Fl::compose() will start out in an initial state. In -particular it will not set "del" to non-zero. This call is very fast -so it is ok to call it many times and in many places. +</UL> -</body></html> +</BODY> +</HTML> diff --git a/documentation/fluid.html b/documentation/fluid.html index af360a96e..eade5232e 100644 --- a/documentation/fluid.html +++ b/documentation/fluid.html @@ -1,20 +1,20 @@ <HTML><BODY> <H1 ALIGN=RIGHT><A NAME=FLUID>8 - Programming with FLUID</A></H1> -This chapter shows how to use the Fast Light User-Interface Designer -("FLUID") to create your GUIs. +This chapter shows how to use the Fast Light User-Interface Designer +("FLUID") to create your GUIs. <H2>What is FLUID?</H2> -<P>The Fast Light User Interface Designer, or FLUID, is a graphical -editor that is used to produce FLTK source code. +<P>The Fast Light User Interface Designer, or FLUID, is a graphical +editor that is used to produce FLTK source code. -<P>FLUID edits and saves its state in <TT>.fl</TT> files. These files are -text, and you can (with care) edit them in a text editor, perhaps to +<P>FLUID edits and saves its state in <TT>.fl</TT> files. These files are +text, and you can (with care) edit them in a text editor, perhaps to get some special effects. </P> -<P>FLUID can "compile" the <TT>.fl</TT> file into a <TT>.cxx</TT> and a <TT>.h</TT> file. The -<TT>.cxx</TT> file defines all the objects from the <TT>.fl</TT> file and the <TT>.h</TT> file +<P>FLUID can "compile" the <TT>.fl</TT> file into a <TT>.cxx</TT> and a <TT>.h</TT> file. The +<TT>.cxx</TT> file defines all the objects from the <TT>.fl</TT> file and the <TT>.h</TT> file declares all the global ones. </P> <P>FLUID also supports localization (<A HREF="#I18N">Internationalization</A>) @@ -22,41 +22,41 @@ of label strings using message files and the GNU gettext or POSIX catgets interfaces. <P>A simple program can be made by putting all your code (including a <TT> -main()</TT> function) into the <TT>.fl</TT> file and thus making the <TT>.cxx</TT> file a -single source file to compile. Most programs are more complex than -this, so you write other <TT>.cxx</TT> files that call the FLUID functions. +main()</TT> function) into the <TT>.fl</TT> file and thus making the <TT>.cxx</TT> file a +single source file to compile. Most programs are more complex than +this, so you write other <TT>.cxx</TT> files that call the FLUID functions. These <TT>.cxx</TT> files must <TT>#include</TT> the <TT>.h</TT> file or they can <TT> -#include</TT> the <TT>.cxx</TT> file so it still appears to be a single source +#include</TT> the <TT>.cxx</TT> file so it still appears to be a single source file. <P ALIGN=CENTER><IMG src="fluid-org.gif" ALT="FLUID organization."> <P>Normally the FLUID file defines one or more functions or classes which -output C++ code. Each function defines a one or more FLTK +output C++ code. Each function defines a one or more FLTK windows, and all the widgets that go inside those windows. </P> -<P>Widgets created by FLUID are either "named", "complex named" or -"unnamed". A named widget has a legal C++ variable identifier as its -name (i.e. only alphanumeric and underscore). In this case FLUID -defines a global variable or class member 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 its 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 +<P>Widgets created by FLUID are either "named", "complex named" or +"unnamed". A named widget has a legal C++ variable identifier as its +name (i.e. only alphanumeric and underscore). In this case FLUID +defines a global variable or class member 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 its 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 is stored. </P> -<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 +<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 <TT>.cxx</TT> file. </P> <H2>Running FLUID Under UNIX</H2> - To run FLUID under UNIX, type: + To run FLUID under UNIX, type: <UL> <PRE> fluid <I>filename.fl</I> &</PRE> </UL> -to edit the <TT>.fl</TT> file <TT>filename.fl</TT>. If the file does not exist -you will get an error pop-up, but if you dismiss it you will be editing -a blank file 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). +to edit the <TT>.fl</TT> file <TT>filename.fl</TT>. If the file does not exist +you will get an error pop-up, but if you dismiss it you will be editing +a blank file 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 filename: </P> <UL> <PRE> @@ -70,25 +70,25 @@ save-as to write it to a file). -bg2 color </PRE> </UL> - 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 + 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. </P> <H2>Running FLUID Under Microsoft Windows</H2> -To run FLUID under WIN32, double-click on the <I>FLUID.exe</I> file. -You can also run FLUID from the Command Prompt window (FLUID always -runs in the background under WIN32). +To run FLUID under WIN32, double-click on the <I>FLUID.exe</I> file. +You can also run FLUID from the Command Prompt window (FLUID always +runs in the background under WIN32). <H2>Compiling <TT>.fl</TT> files</H2> - FLUID can also be called as a command-line "compiler" to create the -<TT>.cxx</TT> and <TT>.h</TT> file from a <TT>.fl</TT> file. To do this type: + FLUID can also be called as a command-line "compiler" to create the +<TT>.cxx</TT> and <TT>.h</TT> file from a <TT>.fl</TT> file. To do this type: <UL><PRE> fluid -c <I>filename.fl</I> </PRE></UL> This will read the <TT>filename.fl</TT> file and write <I>filename.cxx</I> and <I> -filename.h</I>. The directory will be stripped, so they are written to -the current directory always. If there are any errors reading or -writing the files it will print the error and exit with a non-zero +filename.h</I>. The directory will be stripped, so they are written to +the current directory always. If there are any errors reading or +writing the files it will print the error and exit with a non-zero code. In a makefile you can use a line like this: <UL> <PRE> @@ -96,8 +96,8 @@ my_panels.h my_panels.cxx: my_panels.fl fluid -c my_panels.fl </PRE> </UL> - Some versions of make will accept rules like this to allow all <TT>.fl</TT> -files found to be compiled: + Some versions of make will accept rules like this to allow all <TT>.fl</TT> +files found to be compiled: <UL> <PRE> .SUFFIXES: .fl .cxx .h @@ -191,7 +191,7 @@ class CubeView : public Fl_Gl_Window { * CUBECOLOR. */ void drawCube(); - + float vAng,hAng; float xshift,yshift; float boxv0[3];float boxv1[3]; float boxv2[3];float boxv3[3]; @@ -423,11 +423,11 @@ extensions and you are in business. You can include the CubeViewUI.h <H2>FLUID Reference</H2> <H3>The Widget Browser</H3> -The main window shows a menu bar and a scrolling browser of all -the defined widgets. The name of the <TT>.fl</TT> 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. +The main window shows a menu bar and a scrolling browser of all +the defined widgets. The name of the <TT>.fl</TT> 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. The leftmost widgets are the <I>parents</I>, and all the widgets listed below them are their <I>children</I>. Parents don't have to have any children.</P> @@ -435,30 +435,30 @@ any children.</P> <I>classes</I>. Each of these will produce a single C++ public function or class in the output <TT>.cxx</TT> file. Calling the function or instantiating the class will create all of the child widgets. </P> -<P>The second level of the hierarchy contains the <I>windows</I>. Each of these +<P>The second level of the hierarchy contains the <I>windows</I>. Each of these produces an instance of class <tt>Fl_Window</tt>. </P> <P>Below that are either <I>widgets</I> (subclasses of <tt>Fl_Widget</tt>) or <I> -groups</I> of widgets (including other groups). Plain groups are for -layout, navigation, and resize purposes. <I>Tab groups</I> provide the +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> -<P>Widgets are shown in the browser by either their <I>name</I> (such +<P>Widgets are shown in the browser by either their <I>name</I> (such as "main_panel" in the example), or by their <I>type</I> and <I>label</I> (such as "Button "the green""). </P> -<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. Note that hidden children may -be selected even when there is no visual indication of this. -<P>You <I>open</I> widgets by double-clicking on them, or (to open several +<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. Note that hidden children may +be selected even when there is no visual indication of this. +<P>You <I>open</I> widgets by double-clicking on them, or (to open several widgets you have picked) by typing the F1 key. A control panel will appear so you can change the widget(s).</P> <H3>Menu Items</H3> -<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 +<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: </P> <H4>File/Open... (Alt+o)</H4> -Discards the current editing session and reads in a different <TT>.fl</TT> file. +Discards the current editing session and reads in a different <TT>.fl</TT> file. You are asked for confirmation if you have changed the current file. <P>FLUID can also read <tt>.fd</tt> files produced by the Forms and XForms "fdesign" programs. It is best to File/Merge them @@ -469,19 +469,19 @@ 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 <tt>.fd</tt> file with its own format, which fdesign cannot read! </P> <H4>File/Save (Alt+s)</H4> -Writes the current data to the <TT>.fl</TT> file. If the file is unnamed -then FLUID will ask for a filename. +Writes the current data to the <TT>.fl</TT> file. If the file is unnamed +then FLUID will ask for a filename. <H4>File/Save As...(Alt+Shift+S)</H4> Asks for a new filename and saves the file. <H4>File/Merge... (Alt+i)</H4> -Inserts the contents of another <TT>.fl</TT> file, without changing the name of -the current <TT>.fl</TT> file. All the functions (even if they have the same -names as the current ones) are added, and you will have to use cut/paste to -put the widgets where you want. +Inserts the contents of another <TT>.fl</TT> file, without changing the name of +the current <TT>.fl</TT> file. All the functions (even if they have the same +names as the current ones) are added, and you will have to use cut/paste to +put the widgets where you want. <H4>File/Write Code (Alt+Shift+C)</H4> "Compiles" the data into a <TT>.cxx</TT> and <TT>.h</TT> file. These are exactly the same as the files you get when you run -FLUID with the <tt>-c</tt> switch. +FLUID with the <tt>-c</tt> switch. <P>The output file names are the same as the <TT>.fl</TT> file, with the leading directory and trailing ".fl" stripped, and ".h" or ".cxx" appended. </P> @@ -492,65 +492,65 @@ the leading directory and trailing ".fl" stripped, and ".txt", ".po", or ".msg" appended depending on the <A HREF="#I18N">Internationalization Mode</A>. </P> <H4>File/Quit (Alt+q)</H4> -Exits FLUID. You are asked for confirmation if you have changed the -current data. +Exits FLUID. You are asked for confirmation if you have changed the +current data. <H4>Edit/Undo (Alt+z)</H4> This isn't implemented yet. You should do save often so you can -recover from any mistakes you make. +recover from any mistakes you make. <H4>Edit/Cut (Alt+x)</H4> -Deletes the selected widgets and all of their children. These are saved +Deletes the selected widgets and all of their children. These are saved to a "clipboard" file and can be pasted back into any FLUID window. <H4>Edit/Copy (Alt+c)</H4> -Copies the selected widgets and all of their children to the "clipboard" -file. +Copies the selected widgets and all of their children to the "clipboard" +file. <H4>Edit/Paste (Alt+c)</H4> -Pastes the widgets from the clipboard file. -<P>If the widget is a window, it is added to whatever function is +Pastes the widgets from the clipboard file. +<P>If the widget is a window, it is added to whatever function is selected, or contained in the current selection. </P> -<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 +<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> -<P>To avoid confusion, it is best to select exactly one widget before +<P>To avoid confusion, it is best to select exactly one widget before doing a paste. </P> <P>Cut/paste is the only way to change the parent of a widget. </P> <H4>Edit/Select All (Alt+a)</H4> -Selects 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 +Selects 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. </P> <H4>Edit/Open... (F1 or double click)</H4> Displays the current widget in the attributes panel. If the widget is a window and it is not visible then the window is shown instead. <H4>Edit/Sort</H4> -Sorts the selected widgets 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. +Sorts the selected widgets 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. <H4>Edit/Earlier (F2)</H4> -Moves all of the selected widgets one earlier in order among 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, classes, and windows within functions. +Moves all of the selected widgets one earlier in order among 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, classes, and windows within functions. <H4>Edit/Later (F3)</H4> -Moves all of the selected widgets one later in order among the -children of their parent (if possible). +Moves all of the selected widgets one later in order among the +children of their parent (if possible). <H4>Edit/Group (F7)</H4> Creates a new <tt>Fl_Group</tt> and make all the currently selected widgets children of it. <H4>Edit/Ungroup (F8)</H4> Deletes the parent group if all the children of a group are selected. <H4>Edit/Overlays on/off (Alt+Shift+O)</H4> -Toggles 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. +Toggles 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. <H4>Edit/Preferences (Alt+p)</H4> Displays the preferences panel. The alignment preferences control the grid that all widgets snap to when you move and resize them, and for the -"snap" which is how far a widget has to be dragged from its original position +"snap" which is how far a widget has to be dragged from its original position to actually change. <P ALIGN="CENTER"><IMG SRC="fluid_prefs.gif" ALT="FLUID Preferences Window"></P> @@ -563,10 +563,10 @@ file will include the header file automatically. this chapter</A>. <H4>New/Code/Function</H4> -Creates 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 which can be referred to by -code you type into the individual widgets. +Creates 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 which 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 a Fl_Window pointer. The unnamed window will be returned from it (more than one unnamed window is useless). If the function @@ -574,7 +574,7 @@ contains only named windows, it will be declared as returning nothing (<tt>void</tt>). </P> <P>It is possible to make the <TT>.cxx</TT> output be a self-contained program that can be compiled and executed. This is done by deleting -the function name so <tt>main(argc,argv)</tt> is used. The function +the function name so <tt>main(argc,argv)</tt> is used. The function will call <tt>show()</tt> on all the windows it creates and then call <tt>Fl::run()</tt>. This can also be used to test resize behavior or other parts of the user interface.</P> @@ -582,39 +582,39 @@ other parts of the user interface.</P> <H4>New/Window</H4> Creates a new <tt>Fl_Window</tt> widget. The window is added to the currently selected function, or to the function containing the -currently selected item. The window will appear, sized to 100x100. -You can resize it to whatever size you require. +currently selected item. The window will appear, sized to 100x100. +You can resize it to whatever size you require. <P>The widget panel will also appear and is described later in this chapter.</P> <H4>New/...</H4> -All other items on the New menu are subclasses of <tt>Fl_Widget</tt>. 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, +All other items on the New menu are subclasses of <tt>Fl_Widget</tt>. 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, which is described later in this chapter. </P> <H4>Help/About FLUID</H4> -Pops up a panel showing the version of FLUID. +Pops up a panel showing the version of FLUID. <H3>The Widget Panel</H3> -When you double-click on a widget or a set of widgets you will get -the "widget attribute panel". -<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+Shift+O) to hide the red overlay so you can see +When you double-click on a widget or a set of widgets you will get +the "widget attribute panel". +<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+Shift+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> of the selected +<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> of 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 such as mismatched parenthesis in any code before +<P>Hitting "OK" makes the changes permanent. Selecting a different +widget also makes the changes permanent. FLUID checks for simple +syntax errors such as mismatched parenthesis in any code 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 are undone, +<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 are undone, however. <!-- NEW PAGE --> <TABLE cellpadding=0 cellspacing=0 width=100% summary="columns of text"> @@ -622,125 +622,125 @@ however. <TD VALIGN=TOP> <H3><A name=widget_attributes>Widget Attributes</A></H3> <H4>Name (text field)</H4> -Name of a 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 +Name of a 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. </P> <H4>Type (upper-right pulldown menu)</H4> - Some classes have subtypes that modify their appearance or behavior. -You pick the subtype off of this menu. + Some classes have subtypes that modify their appearance or behavior. +You pick the subtype off of this menu. <H4>Box (pulldown menu)</H4> -The boxtype to draw as a background for the widget. +The boxtype to draw as a background for the widget. </TD> <TD> </TD> <TD VALIGN=TOP WIDTH=378><IMG src="fluid_widget.gif" ALT="The FLUID widget dialog."></TD> </TR> </TABLE> -<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 +<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 may leave unwanted stuff inside the widget. </P> -<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. Note -that this checkerboard is not drawn by the resulting program. Instead +<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. Note +that this checkerboard is not drawn by the resulting program. Instead random garbage will be displayed.</P> <H4>Color</H4> <P>The color to draw the box with. </P> <H4>Color2</H4> -<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 +<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. </P> <H4>Label</H4> - String to print next to or inside the button. -<P>You can put newlines into the string to make multiple lines. The + 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. </P> <H4>Label style (pull down menu)</H4> - How to draw the label. Normal, shadowed, engraved, and embossed -change the appearance of the text. "symbol" requires the label to + How to draw the label. Normal, shadowed, engraved, and embossed +change the appearance of the text. "symbol" requires the label to start with an '@' sign to draw a named <A href="common.html#symbols"> -symbol</A>. +symbol</A>. <P>From this menu you can also pick <A href=drawing.html#images> "Image..."</A>. This lets you use the contents of a GIF, XPM, or XBM image file to label the widget. </P> <H4>Label Alignment (Buttons)</H4> - 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. + 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. <H4>Label Font</H4> - 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. + 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. <H4>Label Size</H4> -Pixel size (height) 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. +Pixel size (height) 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. <H4>Label Color</H4> -Color to draw the label. Ignored by pixmaps (bitmaps, however, do use -this color as the foreground color). +Color to draw the label. Ignored by pixmaps (bitmaps, however, do use +this color as the foreground color). <H4>Text Font, Size, and Color</H4> Some widgets display text, such as input fields, pull-down menus, and browsers. <H4>Visible</H4> -If you turn this off then the widget is hidden initially. Don't change -this for windows or for the immediate children of a Tabs group. +If you turn this off then the widget is hidden initially. Don't change +this for windows or for the immediate children of a Tabs group. <H4>Active</H4> If you turn this off then the widget is deactivated initially. <H4>Resizable</H4> -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 +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 the other children. </P> -<P>You can get more complex behavior by making invisible boxes the -resizable widget, or by using hierarchies of groups. Unfortunately the -only way to test it is to compile the program. Resizing the FLUID +<P>You can get more complex behavior by making invisible boxes the +resizable widget, or by using hierarchies of groups. Unfortunately 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. </P> <H4>Hotspot</H4> - 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</I>, so you should call it immediately before showing -the window. 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 <tt>show()</tt>. + 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</I>, so you should call it immediately before showing +the window. 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 <tt>show()</tt>. <H4>Subclass</H4> -This is how you use your own subclasses of <tt>Fl_Widget</tt>. Whatever -identifier you type in here will be the class that is instantiated. -<P>In addition, no <tt>#include</tt> header file is put in the <TT>.h</TT> file. You +This is how you use your own subclasses of <tt>Fl_Widget</tt>. Whatever +identifier you type in here will be the class that is instantiated. +<P>In addition, no <tt>#include</tt> header file is put in the <TT>.h</TT> file. You must provide a <tt>#include</tt> line as the first line of the "Extra Code" which declares your subclass. </P> -<P>The class must 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 +<P>The class must 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. </P> <H4>Extra Code</H4> -These four fields let you type in literal lines of code to dump into -the <TT>.h</TT> or <TT>.cxx</TT> files. -<P>If the text starts with a <tt>#</tt> or the word <tt>extern</tt> then FLUID thinks -this is an "include" line, and it is written to the <TT>.h</TT> file. If the +These four fields let you type in literal lines of code to dump into +the <TT>.h</TT> or <TT>.cxx</TT> files. +<P>If the text starts with a <tt>#</tt> or the word <tt>extern</tt> then FLUID thinks +this is an "include" line, and it is written to the <TT>.h</TT> file. If the same include line occurs several times then only one copy is written. </P> -<P>All other lines are "code" lines. The current widget is -pointed to by the local variable <tt>o</tt>. The window being constructed is -pointed to by the local variable <tt>w</tt>. You can also access any -arguments passed to the function here, and any named widgets that are +<P>All other lines are "code" lines. The current widget is +pointed to by the local variable <tt>o</tt>. The window being constructed is +pointed to by the local variable <tt>w</tt>. You can also access any +arguments passed to the function here, and any named widgets that are before this one. </P> -<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 four lines you probably should call a function in +<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 four lines you probably should call a function in your own <TT>.cxx</TT> code. </P> <H4>Callback</H4> -This can either be the name of a function, or a small snippet of code. +This can either be the name of a function, or a small snippet of code. If you enter anything but letters, numbers, and the underscore then FLUID -treats it as code. -<P>A name names a function in your own code. It must be declared as +treats it as code. +<P>A name names a function in your own code. It must be declared as <tt>void name(<class>*,void*)</tt>. </P> <P>A code snippet is inserted into a static function in the <TT>.cxx</TT> output file. The function prototype is <tt>void @@ -751,131 +751,131 @@ 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> <P>If the callback is blank then no callback is set. </P> <H4>user_data</H4> -This is a value for the <tt>user_data()</tt> of the widget. If blank the -default value of zero is used. This can be any piece of C code that +This is a value for the <tt>user_data()</tt> of the widget. If blank the +default value of zero is used. This can be any piece of C code that can be cast to a <tt>void</tt> pointer. <H4>User Data Type</H4> -The <tt>void *</tt> in the callback function prototypes is replaced with this. -You may want to use <tt>long</tt> for old XForms code. Be warned that -anything other than <tt>void *</tt> is not guaranteed to work! -However on most architectures other pointer types are ok, and <tt>long</tt> is -usually ok, too. +The <tt>void *</tt> in the callback function prototypes is replaced with this. +You may want to use <tt>long</tt> for old XForms code. Be warned that +anything other than <tt>void *</tt> is not guaranteed to work! +However on most architectures other pointer types are ok, and <tt>long</tt> is +usually ok, too. <H4>When</H4> When to do the callback. This can be "never", "changed", -"release", "enter key", or "no change". 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 other rare but useful values for the <tt>when()</tt> field that are -not in the menu. You should use the extra code fields to put these +"release", "enter key", or "no change". 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 other rare but useful values for the <tt>when()</tt> field that are +not in the menu. You should use the extra code fields to put these values in.</P> <H3>Selecting and Moving Widgets</H3> -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-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 +<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> -<P>You cannot pick hidden widgets. You also cannot choose some widgets -if they are completely overlapped by later widgets. Use the browser to +<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> -<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 +<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> -<P>If there is a tab box displayed you can change which child is +<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> -<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 +<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> -<P>To "open" a widget, double click it. To open several widgets select +<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> -<P>Type Alt+o to temporarily toggle the overlay off without changing +<P>Type Alt+o to temporarily toggle the overlay off without changing the selection, so you can see the widget borders. </P> -<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 +<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> -<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 +<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: </P> <H4>Border</H4> - 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. + 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. <H4>xclass</H4> - 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 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. <H3><A name=images>Image Labels</A></H3> -<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" +<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> -<P>The <I>contents</I> of the image file are written to the <TT>.cxx</TT> file, -so if you wish to distribute the C code, you only need to copy the <TT>.cxx</TT> -file, not the images. If many widgets share the same image then only +<P>The <I>contents</I> of the image file are written to the <TT>.cxx</TT> file, +so if you wish to distribute the C code, you only need to copy the <TT>.cxx</TT> +file, not the images. If many widgets share the same image then only one copy is written. </P> -<P>However the <I>file name</I> is stored in the <TT>.fl</TT> file, so to read -the <TT>.fl</TT> file you need the image files as well. Filenames are relative -to the location the <TT>.fl</TT> file is (not necessarily the current -directory). I recommend you either put the images in the same +<P>However the <I>file name</I> is stored in the <TT>.fl</TT> file, so to read +the <TT>.fl</TT> file you need the image files as well. Filenames are relative +to the location the <TT>.fl</TT> file is (not necessarily the current +directory). I recommend you either put the images in the same directory as the <TT>.fl</TT> file, or use absolute path names. </P> <H4>Notes for all image types</H4> -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 +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 +<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> -<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 its internal copy, and then set the image +<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 its internal copy, and then set the image again. You may find it easier to exit FLUID and run it again. </P> -<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 +<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> -<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 +<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. </P> <H4>XBM (X bitmap files)</H4> -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" +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' +<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> -<P>The program "bitmap" on the X distribution does an ok job of editing +<P>The program "bitmap" on the X distribution does an ok job of editing bitmaps. </P> <H4>XPM (X pixmap files)</H4> -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 +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 +<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> -<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 +<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> <P>I have not found any good editors for small iconic pictures. For @@ -886,13 +886,13 @@ color images and are difficult to use to edit an image of small size and few colors. </P> <H4>GIF files</H4> -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 +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 (modified) 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 +<P>FLUID converts these into (modified) 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> <P>Behavior and performance with large .gif files is not guaranteed! </P> <H2><A NAME="I18N">Internationalization with FLUID</A></H2> @@ -905,7 +905,7 @@ use POSIX catgets. The "use none" method is the default and just passes the label strings as-is to the widget constructors. <P>The "GNU gettext" method uses GNU gettext (or a similar text-based I18N library) to retrieve a localized string before calling the widget -constructor. +constructor. <P>The "POSIX catgets" method uses the POSIX catgets function to retrieve a numbered message from a message catalog before calling the widget constructor. diff --git a/documentation/forms.html b/documentation/forms.html index 9b405416b..9d0d7cb88 100644 --- a/documentation/forms.html +++ b/documentation/forms.html @@ -1,69 +1,69 @@ <HTML><BODY> <H1 ALIGN=RIGHT><A NAME=forms>E - Forms Compatibility</A></H1> - This appendix describes the Forms compatibility included with FLTK. + This appendix describes the Forms compatibility included with FLTK. <H2>Importing Forms Layout Files</H2> -<A href=fluid.html#FLUID>FLUID</A> 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 +<A href=fluid.html#FLUID>FLUID</A> 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 compatibility header, <TT> <FL/forms.H></TT>. </P> <H2>Using the Compatibility Header File</H2> - You should be able to compile existing Forms or XForms source code by + You should be able to compile existing Forms or XForms source code by changing the include directory switch to your compiler so that the <TT> forms.h</TT> file supplied with FLTK is included. Take a look at <TT> -forms.h</TT> to see how it works, but the basic trick is lots of inline -functions. Most of the XForms demo programs work without changes. -<P>You will also have to compile your Forms or XForms program using a -C++ compiler. The FLTK library does not provide C bindings or header +forms.h</TT> to see how it works, but the basic trick is lots of inline +functions. Most of the XForms demo programs work without changes. +<P>You will also have to compile your Forms or XForms program using a +C++ compiler. The FLTK library does not provide C bindings or header files. </P> -<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 compatibility is no longer -a goal of FLTK. Compatibility was limited to things that were free, or -that would add code that would not be linked in if the feature is +<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 compatibility is no longer +a goal of FLTK. Compatibility was limited to things that were free, or +that would add code that would not be linked in if the feature is unused, or that was not X-specific. </P> -<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 expected and +<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 expected and even Digital Domain's inhouse code still uses <TT>forms.H</TT> a lot. </P> <H2>Problems You Will Encounter</H2> <P>Many parts of XForms use X-specific structures like <TT>XEvent</TT> - in their interface. I did not emulate these! Unfortunately these -features (such as the "canvas" widget) are needed by most large + 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> -<P><A href=Fl_Free.html#Fl_Free><TT>Fl_Free</TT></A> widgets emulate -the <I>old</I> Forms "free" widget. It may be useful for porting -programs that change the <TT>handle()</TT> function on widgets, but you +<P><A href=Fl_Free.html#Fl_Free><TT>Fl_Free</TT></A> widgets emulate +the <I>old</I> Forms "free" widget. It may be useful for porting +programs that change the <TT>handle()</TT> function on widgets, but you will still need to rewrite things. </P> -<P><A href=Fl_Timer.html#Fl_Timer><TT>Fl_Timer</TT></A> widgets are -provided to emulate the XForms timer. These work, but are quite +<P><A href=Fl_Timer.html#Fl_Timer><TT>Fl_Timer</TT></A> widgets are +provided to emulate the XForms timer. These work, but are quite inefficient and inaccurate compared to using <A href=functions.html#add_timeout> <TT>Fl::add_timeout()</TT></A>. </P> -<P><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 +<P><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> -<P><TT>const char *</TT> arguments to most FLTK methods are simply -stored, while Forms would <TT>strdup()</TT> the passed string. This is -most noticable with the label of widgets. Your program must always +<P><TT>const char *</TT> arguments to most FLTK methods are simply +stored, while Forms would <TT>strdup()</TT> 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 <TT> -label()</TT>. If you are using labels to display program output you +label()</TT>. If you are using labels to display program output you may want to try the <A href=Fl_Output.html#Fl_Output><TT>Fl_Output</TT></A> widget. </P> -<P>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 +<P>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> -<P>fdesign outputs a setting of a "fdui" instance variable to the main -window. I did not emulate this because I wanted all instance variables +<P>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 <TT>user_data()</TT> - field of a window. To do this, search through the fdesign output for -all occurances of "->fdui" and edit to use "->user_data()" instead. + 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> <P>The prototype for the functions passed to <TT>fl_add_timeout()</TT> and <TT>fl_set_idle_callback()</TT> callback are different. </P> @@ -116,55 +116,55 @@ all occurances of "->fdui" and edit to use "->user_data()&q <LI>xyplot object </LI> </UL> <H2>Additional Notes</H2> - These notes were written for porting programs written with the older -IRISGL version of Forms. Most of these problems are the same ones -encountered when going from old Forms to XForms: + These notes were written for porting programs written with the older +IRISGL version of Forms. Most of these problems are the same ones +encountered when going from old Forms to XForms: <H3>Does Not Run In Background</H3> - The IRISGL 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. + The IRISGL 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. <H3>You Cannot Use IRISGL Windows or fl_queue</H3> - If a Forms (not XForms) program if you wanted your own window for -displaying things you would create a IRISGL 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 IRISGL 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 + If a Forms (not XForms) program if you wanted your own window for +displaying things you would create a IRISGL 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 IRISGL 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> <P>You have to make a subclass of <A href=Fl_Gl_Window.html#Fl_Gl_Window> <TT>Fl_Gl_Window</TT></A> and write a <TT>draw()</TT> method and <TT> -handle()</TT> method. This may require anywhere from a trivial to a +handle()</TT> method. This may require anywhere from a trivial to a major rewrite. </P> <P>If you draw into the overlay planes you will have to also write a <TT> -draw_overlay()</TT> method and call <TT>redraw_overlay()</TT> on the +draw_overlay()</TT> method and call <TT>redraw_overlay()</TT> on the OpenGL window. </P> <P>One easy way to hack your program so it works is to make the <TT> -draw()</TT> and <TT>handle()</TT> methods on your window set some -static variables, storing what event happened. Then in the main loop -of your program, call <TT>Fl::wait()</TT> and then check these +draw()</TT> and <TT>handle()</TT> methods on your window set some +static variables, storing what event happened. Then in the main loop +of your program, call <TT>Fl::wait()</TT> and then check these variables, acting on them as though they are events read from <TT> fl_queue</TT>. </P> <H3>You Must Use OpenGL to Draw Everything</H3> -<P>The file <TT><FL/gl.h></TT> defines replacements for a lot of IRISGL -calls, translating them to OpenGL. There are much better translators +<P>The file <TT><FL/gl.h></TT> defines replacements for a lot of IRISGL +calls, translating them to OpenGL. There are much better translators available that you might want to investigate. </P> <H3>You Cannot Make Forms Subclasses</H3> - Programs that call <TT>fl_make_object</TT> or directly setting the -handle routine will not compile. You have to rewrite them to use a + Programs that call <TT>fl_make_object</TT> or directly setting the +handle routine will not compile. You have to rewrite them to use a subclass of <TT>Fl_Widget</TT>. It is important to note that the <TT> handle()</TT> method is not exactly the same as the <TT>handle()</TT> - function of Forms. Where a Forms <TT>handle()</TT> returned non-zero, + function of Forms. Where a Forms <TT>handle()</TT> returned non-zero, your <TT>handle()</TT> must call <TT>do_callback()</TT>. And your <TT> -handle()</TT> 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 +handle()</TT> 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> -<P>If your subclass draws into the overlay you are in trouble and will +<P>If your subclass draws into the overlay you are in trouble and will have to rewrite things a lot. </P> <H3>You Cannot Use <device.h></H3> - If you have written your own "free" widgets you will probably get a -lot of errors about "getvaluator". You should substitute: + If you have written your own "free" widgets you will probably get a +lot of errors about "getvaluator". You should substitute: <CENTER><TABLE border=1 WIDTH=90% summary="Mapping of Forms valuators to FLTK."> <TR><TH align=center>Forms</TH><TH align=center>FLTK</TH></TR> <TR><TD>MOUSE_X</TD><TD>Fl::event_x_root()</TD></TR> @@ -177,12 +177,12 @@ lot of errors about "getvaluator". You should substitute: <TR><TD>MOUSE2,MIDDLEMOUSE</TD><TD>Fl::event_state()</TD></TR> <TR><TD>MOUSE3,LEFTMOUSE</TD><TD>Fl::event_state()</TD></TR> </TABLE></CENTER> - Anything else in <TT>getvaluator</TT> and you are on your own... + Anything else in <TT>getvaluator</TT> and you are on your own... <H3>Font Numbers Are Different</H3> - 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: + 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*"); diff --git a/documentation/glut.html b/documentation/glut.html index c26ee7352..93d7b30e8 100644 --- a/documentation/glut.html +++ b/documentation/glut.html @@ -1,31 +1,31 @@ <HTML><BODY> <H1 ALIGN=RIGHT><A NAME=glut>D - GLUT Compatibility</A></H1> - This appendix describes the GLUT compatibility header file supplied -with FLTK. + This appendix describes the GLUT compatibility header file supplied +with FLTK. <H2>Using the GLUT Compatibility Header File</H2> You should be able to compile existing GLUT source code by including <TT> -<FL/glut.H></TT> instead of <TT><GL/glut.h></TT>. This can be done by -editing the source, by changing the <TT>-I</TT> switches to the +<FL/glut.H></TT> instead of <TT><GL/glut.h></TT>. This can be done by +editing the source, by changing the <TT>-I</TT> switches to the compiler, or by providing a symbolic link from <TT>GL/glut.h</TT> to <TT> -FL/glut.H</TT>. -<P><I>All files calling GLUT procedures must be compiled with C++</I>. - 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++ +FL/glut.H</TT>. +<P><I>All files calling GLUT procedures must be compiled with C++</I>. + 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. </P> -<P>You must link with the FLTK library. If you call any GLUT drawing +<P>You must link with the FLTK library. If you call any GLUT drawing functions that FLTK does not emulate (<TT>glutExtensionsSupported()</TT> , <TT>glutWire*()</TT>, <TT>glutSolid*()</TT>, and <TT>glutStroke*()</TT> -), you will also have to link with the GLUT library (<I>after</I> the +), you will also have to link with the GLUT library (<I>after</I> the FLTK library!) </P> -<P>Most of <TT>FL/glut.H</TT> is inline functions. You should take a -look at it (and maybe at <TT>test/glpuzzle.cxx</TT> in the FLTK source) if +<P>Most of <TT>FL/glut.H</TT> is inline functions. You should take a +look at it (and maybe at <TT>test/glpuzzle.cxx</TT> in the FLTK source) if you are having trouble porting your GLUT program. </P> -<P>This has been tested with most of the demo programs that come with +<P>This has been tested with most of the demo programs that come with the GLUT 3.3 distribution. </P> <H2>Known Problems</H2> - 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: + 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><TT>glutLayerGet(GLUT_LAYER_IN_USE)</TT></LI> <LI><TT>glutLayerGet(GLUT_HAS_OVERLAY)</TT></LI> @@ -43,53 +43,53 @@ compile: <LI><TT>glutGet(GLUT_ELAPSED_TIME)</TT></LI> <LI><TT>glutVideoResize()</TT> missing. </LI> </UL> - Most of the symbols/enumerations have different values than GLUT uses. - This will break code that relies on the actual values. The only + 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 <TT> GLUT_DOWN</TT> and <TT>GLUT_UP</TT>, mouse buttons <TT> GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON, GLUT_RIGHT_BUTTON</TT>, and <TT> -GLUT_KEY_F1</TT> thru <TT>F12</TT>. +GLUT_KEY_F1</TT> thru <TT>F12</TT>. <P>The strings passed as menu labels are not copied. </P> -<P><TT>glutPostRedisplay()</TT> does not work if called from inside a -display function. You must use <TT>glutIdleFunc()</TT> if you want +<P><TT>glutPostRedisplay()</TT> does not work if called from inside a +display function. You must use <TT>glutIdleFunc()</TT> if you want your display to update continuously. </P> -<P><TT>glutSwapBuffers()</TT> does not work from inside a display +<P><TT>glutSwapBuffers()</TT> does not work from inside a display function. This is on purpose, because FLTK swaps the buffers for you. </P> -<P><TT>glutUseLayer()</TT> does not work well, and should only be used -to initialize transformations inside a resize callback. You should +<P><TT>glutUseLayer()</TT> does not work well, and should only be used +to initialize transformations inside a resize callback. You should redraw overlays by using <TT>glutOverlayDisplayFunc()</TT>. </P> <P>Overlays are cleared before the overlay display function is called. <TT> -glutLayerGet(GLUT_OVERLAY_DAMAGED)</TT> always returns true for -compatibility with some GLUT overlay programs. You must rewrite your -code so that <TT>gl_color()</TT> is used to choose colors in an +glutLayerGet(GLUT_OVERLAY_DAMAGED)</TT> always returns true for +compatibility with some GLUT overlay programs. You must rewrite your +code so that <TT>gl_color()</TT> is used to choose colors in an overlay, or you will get random overlay colors. </P> -<P><TT>glutSetCursor(GLUT_CURSOR_FULL_CROSSHAIR)</TT> just results in a +<P><TT>glutSetCursor(GLUT_CURSOR_FULL_CROSSHAIR)</TT> just results in a small crosshair. </P> <P>The fonts used by <TT>glutBitmapCharacter() and glutBitmapWidth()</TT> may be different. </P> -<P><TT>glutInit(argc,argv)</TT> will consume different switches than +<P><TT>glutInit(argc,argv)</TT> will consume different switches than GLUT does. It accepts the switches recognized by <A href=functions.html#args> -<TT>Fl::args()</TT></A>, and will accept any abbreviation of these +<TT>Fl::args()</TT></A>, and will accept any abbreviation of these switches (such as "-di" for "-display"). </P> <H2>Mixing GLUT and FLTK Code</H2> - You can make your GLUT window a child of a <TT>Fl_Window</TT> with the + You can make your GLUT window a child of a <TT>Fl_Window</TT> with the following scheme. The biggest trick is that GLUT insists on <TT>show()</TT> 'ing the window at the point it is created, which means the <TT> -Fl_Window</TT> parent window must already be shown. +Fl_Window</TT> parent window must already be shown. <UL> <LI>Don't call <TT>glutInit()</TT>. </LI> -<LI>Create your <TT>Fl_Window</TT>, and any FLTK widgets. Leave a +<LI>Create your <TT>Fl_Window</TT>, and any FLTK widgets. Leave a blank area in the window for your GLUT window. </LI> <LI><TT>show()</TT> the <TT>Fl_Window</TT>. Perhaps call <TT> show(argc,argv)</TT>. </LI> -<LI>Call <TT>window->begin()</TT> so that the GLUT window will be +<LI>Call <TT>window->begin()</TT> so that the GLUT window will be automatically added to it. </LI> <LI>Use <TT>glutInitWindowSize()</TT> and <TT>glutInitWindowPosition()</TT> to set the location in the parent window to put the GLUT window. </LI> -<LI>Put your GLUT code next. It probably does not need many changes. +<LI>Put your GLUT code next. It probably does not need many changes. Call <TT>window->end()</TT> immediately after the <TT> glutCreateWindow()</TT>! </LI> -<LI>You can call either <TT>glutMainLoop()</TT>, <TT>Fl::run()</TT>, or +<LI>You can call either <TT>glutMainLoop()</TT>, <TT>Fl::run()</TT>, or loop calling <TT>Fl::wait()</TT> to run the program. </LI> </UL> <HR break> @@ -110,18 +110,18 @@ loop calling <TT>Fl::wait()</TT> to run the program. </LI> </PRE> </UL> <H3>Description</H3> - Each GLUT window is an instance of this class. 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 FLTK's method of creating windows. + Each GLUT window is an instance of this class. 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 FLTK's method of creating windows. <P>The current GLUT window is available in the global variable <TT> glut_window</TT>. </P> <P><TT>new Fl_Glut_Window(...)</TT> is the same as <TT> -glutCreateWindow()</TT> except it does not <TT>show()</TT> the window +glutCreateWindow()</TT> except it does not <TT>show()</TT> the window or make the window current. </P> <P><TT>window->make_current()</TT> is the same as <TT> glutSetWindow(number)</TT>. If the window has not had <TT>show()</TT> - called on it yet, some functions that assumme an OpenGL context will + called on it yet, some functions that assumme an OpenGL context will not work. If you do <TT>show()</TT> the window, call <TT>make_current()</TT> again to set the context. </P> <P><TT>~Fl_Glut_Window()</TT> is the same as <TT>glutDestroyWindow()</TT> @@ -192,15 +192,15 @@ be altered directly: <LI><A href=#Fl_Glut_Window.make_current>make_current</A></LI> </UL> <H4><A name=Fl_Glut_Window.Fl_Glut_Window> -Fl_Glut_Window::Fl_Glut_Window(int x, int y, int w, int h, const char +Fl_Glut_Window::Fl_Glut_Window(int x, int y, int w, int h, const char *title = 0) <BR> Fl_Glut_Window::Fl_Glut_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. -<H4><A name=Fl_Glut_Window.~Fl_Glut_Window>virtual + 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. +<H4><A name=Fl_Glut_Window.~Fl_Glut_Window>virtual Fl_Glut_Window::~Fl_Glut_Window()</A></H4> Destroys the GLUT window. <H4><A name="Fl_Glut_Window.make_current">void Fl_Glut_Window::make_current()</A></H4> diff --git a/documentation/index.html b/documentation/index.html index 79a8f83b8..b9483d57e 100644 --- a/documentation/index.html +++ b/documentation/index.html @@ -54,7 +54,7 @@ <LI><A HREF="events.html#event_xxx">Fl::event_*() methods</A></LI> <LI><A HREF="events.html#propagation">Event Propagation</A></LI> </UL> - <B><A HREF="subclassing.html#subclassing">7 - Adding and Extending + <B><A HREF="subclassing.html#subclassing">7 - Adding and Extending Widgets</A></B> </TD> <TD ALIGN=LEFT VALIGN=TOP WIDTH=300> diff --git a/documentation/intro.html b/documentation/intro.html index c92b860af..abdf5a454 100644 --- a/documentation/intro.html +++ b/documentation/intro.html @@ -20,7 +20,7 @@ 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 +ignored NextStep) provided this, but they chose to hide it and tried to push their own baroque toolkit instead.</P> <P>Many of the ideas in FLTK were developed on a NeXT (but @@ -54,7 +54,7 @@ he integrated his table-driven menus into it. Several very large programs were created using this version of Forms.</P> <P>The need to switch to OpenGL and GLX, portability, and a -desire to use C++ subclassing required a rewrite of Forms. +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 incompatible anyway, Bill decided @@ -106,7 +106,7 @@ is now included with several Linux distributions.</P> WIN32 version - only about 10% of the code is different.</LI> - <LI>Interactive user interface builder program. Output is + <LI>Interactive user interface builder program. Output is human-readable and editable C++ source code.</LI> <LI>Support for overlay hardware, with emulation if none @@ -145,7 +145,7 @@ 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 +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", including a bogus excuse that it @@ -159,7 +159,7 @@ everything.</P> <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 and OpenGL (or Mesa) header and library files. +for are the X11 and OpenGL (or Mesa) header and library files. If these cannot be found in the standard include/library locations you'll need to define the <tt>CFLAGS</tt>, <tt>CXXFLAGS</tt>, and <tt>LDFLAGS</tt> environment variables. @@ -231,13 +231,13 @@ tool, and all of the test programs.</P> <P>To install the library, become root and type "make install". This will copy the "fluid" executable -to "bindir", the header files to +to "bindir", the header files to "includedir", and the library files to "libdir".</P> <H2>Building FLTK Under Microsoft Windows</H2> -<P>There are three ways to build FLTK under Microsoft Windows. +<P>There are three 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> @@ -286,7 +286,7 @@ EMX 0.9d and libExt (from <A HREF="http://posix2.sourceforge.net">posix2.sourceforge.net</A>) is installed. -<P>To build the XFree86 version of FLTK for OS/2, copy the appropriate +<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: </P> <UL><PRE> @@ -320,9 +320,9 @@ interface, so XFree86 will no longer be required.</P> <DD><A HREF="ftp://gd.tuwien.ac.at/hci/fltk">Austria (gd.tuwien.ac.at)</A> <DT>EMail</DT> - <DD><A href="mailto:fltk@fltk.org">fltk@fltk.org</A> [see + <DD><A href="mailto:fltk@fltk.org">fltk@fltk.org</A> [see instructions below] - <DD><A href="mailto:fltk-bugs@fltk.org">fltk-bugs@fltk.org</A> [for + <DD><A href="mailto:fltk-bugs@fltk.org">fltk-bugs@fltk.org</A> [for reporting bugs] <DT>News</DT> @@ -335,7 +335,7 @@ interface, so XFree86 will no longer be required.</P> Non-member submissions are blocked to avoid problems with unsolicited email.</P> -<P>To join the FLTK mailing list, send a message to +<P>To join the FLTK mailing list, send a message to "majordomo@fltk.org" with "subscribe fltk" in the message body. A digest of this list is available by subscribing to the "fltk-digest" mailing list.</P> @@ -351,7 +351,7 @@ any kind of help without that basic information.</P> <P>Bugs can also be reported to the "fltk.bugs" newsgroup or on the SourceForge bug tracker pages.</P> -<P>For general support and questions, please use the FLTK mailing list +<P>For general support and questions, please use the FLTK mailing list at "fltk@fltk.org" or one of the newsgroups.</P> </BODY> diff --git a/documentation/license.html b/documentation/license.html index 78b484e0f..cad2b3c6a 100644 --- a/documentation/license.html +++ b/documentation/license.html @@ -4,376 +4,376 @@ <P ALIGN=CENTER>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 +<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 +<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.] </P> <P><BIG>Preamble</BIG></P> - 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 + 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> -<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 +<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> -<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 +<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> -<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 +<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> -<P>Our method of protecting your rights has two steps: (1) copyright -the library, and (2) offer you this license which gives you legal +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<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, +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<P>Note that it is possible for a library to be covered by the ordinary +<P>Note that it is possible for a library to be covered by the ordinary General Public License rather than by this special one. </P> -<P ALIGN="CENTER"><BIG>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND +<P ALIGN="CENTER"><BIG>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</BIG></P> -<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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.) </P> </BLOCKQUOTE> -<P>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 +<P>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> -<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<P>This option is useful when you wish to copy part of the code of the +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<P><STRONG>c)</STRONG> If distribution of the work is made by offering -access to copy from a designated place, offer equivalent access to +<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> -<P><STRONG>d)</STRONG> Verify that the user has already received a copy +<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. </P> </BLOCKQUOTE> -<P>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 +<P>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> -<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 +<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> -<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 +<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 +<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. </P> </BLOCKQUOTE> -<P><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 +<P><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> -<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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> -<P>This section is intended to make thoroughly clear what is believed +<P>This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. </P> -<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 +<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> -<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 +<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> -<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 +<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> -<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 +<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. </P> <P ALIGN="CENTER"><BIG>NO WARRANTY</BIG></P> -<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 +<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> -<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 +<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. </P> <P ALIGN="CENTER"><BIG>END OF TERMS AND CONDITIONS</BIG></P> </BODY></HTML> diff --git a/documentation/migration.html b/documentation/migration.html index 45e032a2b..df84ff088 100644 --- a/documentation/migration.html +++ b/documentation/migration.html @@ -15,6 +15,6 @@ to be ported to the new <CODE>Fl_File_Chooser</CODE> class.</P> <H2>The Image Class</H2> -<P>The <CODE>Fl_Image</CODE> class +<P>The <CODE>Fl_Image</CODE> class </BODY> </HTML> diff --git a/documentation/opengl.html b/documentation/opengl.html index a5336af42..b390e46b9 100644 --- a/documentation/opengl.html +++ b/documentation/opengl.html @@ -1,27 +1,27 @@ <HTML><BODY> <H1 ALIGN=RIGHT><A NAME=opengl>9 - Using OpenGL</A></H1> - This chapter discusses using FLTK for your OpenGL applications. + This chapter discusses using FLTK for your OpenGL applications. <H2>Using OpenGL in FLTK</H2> The easiest way to make an OpenGL display is to subclass <A href=Fl_Gl_Window.html#Fl_Gl_Window> <TT>Fl_Gl_Window</TT></A>. Your subclass must implement a <TT>draw()</TT> -method which uses OpenGL calls to draw the display. Your main program -should call <TT>redraw()</TT> when the display needs to change, and -(somewhat later) FLTK will call <TT>draw()</TT>. -<P>With a bit of care you can also use OpenGL to draw into normal FLTK -windows. This allows you to use Gouraud shading for +method which uses OpenGL calls to draw the display. Your main program +should call <TT>redraw()</TT> when the display needs to change, and +(somewhat later) FLTK will call <TT>draw()</TT>. +<P>With a bit of care you can also use OpenGL to draw into normal FLTK +windows. This allows you to use Gouraud shading for drawing your widgets. To do this you use the <A href=#gl_start><TT> gl_start()</TT></A> and <A href=#gl_finish><TT>gl_finish()</TT></A> functions around your OpenGL code. </P> -<P>You must include FLTK's <TT><FL/gl.h></TT> header file. It will -include the file <TT><GL/gl.h></TT>, define some extra drawing -functions provided by FLTK, and include the <TT><windows.h></TT> header +<P>You must include FLTK's <TT><FL/gl.h></TT> header file. It will +include the file <TT><GL/gl.h></TT>, define some extra drawing +functions provided by FLTK, and include the <TT><windows.h></TT> header file needed by WIN32 applications. </P> <H2>Making a Subclass of Fl_Gl_Window</H2> -To make a subclass of Fl_Gl_Window, you must provide: +To make a subclass of Fl_Gl_Window, you must provide: <UL> <LI>A class definition. </LI> <LI>A <TT>draw()</TT> method. </LI> -<LI>A <TT>handle()</TT> method (if you need to receive input from the +<LI>A <TT>handle()</TT> method (if you need to receive input from the user). </LI> </UL> If your subclass provides static controls in the window, they must be @@ -43,7 +43,7 @@ glDrawBuffer(GL_BACK); considerably. The preprocessor instructions shown above will optimize your code based upon the graphics library used. <H3>Defining the Subclass</H3> -To define the subclass you just subclass the <TT>Fl_Gl_Window</TT> class: +To define the subclass you just subclass the <TT>Fl_Gl_Window</TT> class: <UL> <PRE> class MyWindow : public Fl_Gl_Window { @@ -56,12 +56,12 @@ public: }; </PRE> </UL> - The <TT>draw()</TT> and <TT>handle()</TT> methods are described below. - Like any widget, you can include additional private and public data in -your class (such as scene graph information, etc.) + The <TT>draw()</TT> and <TT>handle()</TT> methods are described below. + Like any widget, you can include additional private and public data in +your class (such as scene graph information, etc.) <H3>The draw() Method</H3> - The <TT>draw()</TT> method is where you actually do your OpenGL -drawing: + The <TT>draw()</TT> method is where you actually do your OpenGL +drawing: <UL> <PRE> void MyWindow::draw() { @@ -75,8 +75,8 @@ void MyWindow::draw() { </PRE> </UL> <H3>The handle() Method</H3> - The <TT>handle()</TT> method handles mouse and keyboard events for the -window: + The <TT>handle()</TT> method handles mouse and keyboard events for the +window: <UL> <PRE> int MyWindow::handle(int event) { @@ -88,7 +88,7 @@ int MyWindow::handle(int event) { case FL_DRAG: ... mouse moved while down event ... return 1; - case FL_RELEASE: + case FL_RELEASE: ... mouse up event ... return 1; case FL_FOCUS : @@ -110,11 +110,11 @@ int MyWindow::handle(int event) { } </PRE> </UL> -When <TT>handle()</TT> is called, the OpenGL context is not set up! +When <TT>handle()</TT> is called, the OpenGL context is not set up! If your display changes, you should call <TT>redraw()</TT> and let <TT> -draw()</TT> do the work. Don't call any OpenGL drawing functions from -inside <TT>handle()</TT>! -<P>You can call <I>some</I> OpenGL stuff like hit detection and texture +draw()</TT> do the work. Don't call any OpenGL drawing functions from +inside <TT>handle()</TT>! +<P>You can call <I>some</I> OpenGL stuff like hit detection and texture loading functions by doing: </P> <UL> <PRE> @@ -128,26 +128,26 @@ loading functions by doing: </P> detection, loading textures, etc... </PRE> </UL> -Your main program can now create one of your windows by doing <TT>new +Your main program can now create one of your windows by doing <TT>new MyWindow(...)</TT>. You can also use <A href=FLUID.html#FLUID>FLUID</A> -by: +by: <OL> <LI>Putting your class definition in a <tt>MyWindow.H</tt> file. </LI> <LI>Creating a <tt>Fl_Box</tt> widget in FLUID.</LI> -<LI>In the widget panel fill in the "class" field with <tt>MyWindow</tt>. +<LI>In the widget panel fill in the "class" field with <tt>MyWindow</tt>. This will make FLUID produce constructors for your new class. </LI> -<LI>In the "Extra Code" field put <TT>#include "MyWindow.H"</TT>, so that +<LI>In the "Extra Code" field put <TT>#include "MyWindow.H"</TT>, so that the FLUID output file will compile. </LI> </OL> You must put <TT>glwindow->show()</TT> in your main code after calling <TT> -show()</TT> on the window containing the OpenGL window. +show()</TT> on the window containing the OpenGL window. <H2>Using OpenGL in Normal FLTK Windows</H2> You can put OpenGL code into an <A href="subclassing.html#draw"><TT>Fl_Widget::draw()</TT> </A> method or into the code for a <A href=common.html#boxtypes>boxtype</A> -or other places with some care. -<P>Most importantly, before you show <I>any</I> windows (including those -that don't have OpenGL drawing) you <B>must</B> initialize FLTK so that it -knows it is going to use OpenGL. You may use any of the symbols +or other places with some care. +<P>Most importantly, before you show <I>any</I> windows (including those +that don't have OpenGL drawing) you <B>must</B> initialize FLTK so that it +knows it is going to use OpenGL. You may use any of the symbols described for <A href=Fl_Gl_Window.html#Fl_Gl_Window.mode><TT> Fl_Gl_Window::mode()</TT></A> to describe how you intend to use OpenGL: </P> <UL> @@ -155,8 +155,8 @@ Fl_Gl_Window::mode()</TT></A> to describe how you intend to use OpenGL: </P> Fl::gl_visual(FL_RGB); </PRE> </UL> -You can then put OpenGL drawing code anywhere you can draw normally by -surrounding it with: +You can then put OpenGL drawing code anywhere you can draw normally by +surrounding it with: <UL> <PRE> gl_start(); @@ -165,18 +165,18 @@ gl_finish(); </PRE> </UL> <A name=gl_start><TT>gl_start()</TT></A> and <A name=gl_finish><TT> -gl_finish()</TT></A> set up an OpenGL context with an orthographic -projection so that 0,0 is the lower-left corner of the window and each +gl_finish()</TT></A> set up an OpenGL 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 <TT> -glScissor()</TT> commands. These also synchronize the OpenGL graphics -stream with the drawing done by other X, WIN32, or FLTK functions. -<P>The same context is reused each time. If your code changes the +glScissor()</TT> commands. These also synchronize the OpenGL graphics +stream with the drawing done by other X, WIN32, or FLTK functions. +<P>The same context is reused each time. If your code changes the projection transformation or anything else you should use <TT> -glPushMatrix()</TT> and <TT>glPopMatrix()</TT> functions to put the +glPushMatrix()</TT> and <TT>glPopMatrix()</TT> functions to put the state back before calling <TT>gl_finish()</TT>. </P> -<P>You may want to use <TT>Fl_Window::current()->h()</TT> to get the +<P>You may want to use <TT>Fl_Window::current()->h()</TT> to get the drawable height so that you can flip the Y coordinates. </P> -<P>Unfortunately, there are a bunch of limitations you must adhere to +<P>Unfortunately, there are a bunch of limitations you must adhere to for maximum portability: </P> <UL> <LI>You must choose a default visual with <A href=functions.html#gl_visual> @@ -184,47 +184,47 @@ for maximum portability: </P> <LI>You cannot pass <TT>FL_DOUBLE</TT> to <TT>Fl::gl_visual()</TT>.</LI> <LI>You cannot use <TT>Fl_Double_Window</TT> or <TT>Fl_Overlay_Window</TT>.</LI> </UL> -Do <I>not</I> call <TT>gl_start()</TT> or <TT>gl_finish()</TT> when +Do <I>not</I> call <TT>gl_start()</TT> or <TT>gl_finish()</TT> when drawing into an <TT>Fl_Gl_Window</TT>! <H2>OpenGL Drawing Functions</H2> -FLTK provides some useful OpenGL drawing functions. They can be +FLTK provides some useful OpenGL drawing functions. They can be freely mixed with any OpenGL calls, and are defined by including <TT> <FL/gl.H></TT> (which you should include instead of the OpenGL header <TT> -<GL/gl.h></TT>). +<GL/gl.h></TT>). <H4>void gl_color(Fl_Color)</H4> -Set the current color to a FLTK color. <I>For color-index modes -it will use <TT>fl_xpixel(c)</TT>, which is only right if this window +Set the current color to a FLTK color. <I>For color-index modes +it will use <TT>fl_xpixel(c)</TT>, which is only right if this window uses the default colormap!</I> <H4>void gl_rect(int x, int y, int w, int h) <BR> void gl_rectf(int x, int y, int w, int h)</H4> Outline or fill a rectangle with the current color. If <A HREF="Fl_Gl_Window.html#Fl_Gl_Window.ortho"><TT>Fl_Gl_Window::ortho()</TT></A> -has been called, then the rectangle will exactly fill the pixel -rectangle passed. +has been called, then the rectangle will exactly fill the pixel +rectangle passed. <H4>void gl_font(Fl_Font fontid, int size)</H4> Set the current OpenGL font to the same font you get by calling <A href=drawing.html#fl_font> -<TT>fl_font()</TT></A>. +<TT>fl_font()</TT></A>. <H4>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)</H4> - Return information about the current OpenGL font. + Return information about the current OpenGL font. <H4>void gl_draw(const char *) <BR> void gl_draw(const char *, int n)</H4> -Draw a nul-terminated string or an array of <TT>n</TT> characters in +Draw a nul-terminated string or an array of <TT>n</TT> characters in the current OpenGL font at the current raster position. <H4>void gl_draw(const char *, int x, int y) <BR> void gl_draw(const char *, int n, int x, int y) <BR> void gl_draw(const char *, float x, float y) <BR> void gl_draw(const char *, int n, float x, float y)</H4> - Draw a nul-terminated string or an array of <TT>n</TT> characters in -the current OpenGL font at the given position. + Draw a nul-terminated string or an array of <TT>n</TT> characters in +the current OpenGL font at the given position. <H4>void gl_draw(const char *, int x, int y, int w, int h, Fl_Align)</H4> - Draw a string formatted into a box, with newlines and tabs expanded, -other control characters changed to ^X, and aligned with the edges or + 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="drawing.html#text"><TT>fl_draw()</TT></A> -. +. <h2>Speeding up OpenGL</h2> @@ -265,14 +265,14 @@ exit and run the program again for it to see any changes to the environment variable. <H2>Using OpenGL Optimizer with FLTK</H2> -<A href=http://www.sgi.com/software/optimizer>OpenGL Optimizer</A> is a -scene graph toolkit for OpenGL available from Silicon Graphics for IRIX -and Microsoft Windows. Versions are in the works for Solaris and -HP-UX. It allows you to view large scenes without writing a lot of -OpenGL code. +<A href=http://www.sgi.com/software/optimizer>OpenGL Optimizer</A> is a +scene graph toolkit for OpenGL available from Silicon Graphics for IRIX +and Microsoft Windows. Versions are in the works for Solaris and +HP-UX. It allows you to view large scenes without writing a lot of +OpenGL code. <H4>OptimizerWindow Class Definition</H4> To use OpenGL Optimizer with FLTK you'll need to create a subclass of <TT> -Fl_Gl_Widget</TT> that includes several state variables: +Fl_Gl_Widget</TT> that includes several state variables: <UL> <PRE> class OptimizerWindow : public Fl_Gl_Window { @@ -307,12 +307,12 @@ public: </UL> <H4>The camera() Method</H4> - The <TT>camera()</TT> method sets the camera (projection and -viewpoint) to use when drawing the scene. The scene is redrawn after -this call. + The <TT>camera()</TT> method sets the camera (projection and +viewpoint) to use when drawing the scene. The scene is redrawn after +this call. <H4>The draw() Method</H4> - The <TT>draw()</TT> method performs the needed initialization and does -the actual drawing: + The <TT>draw()</TT> method performs the needed initialization and does +the actual drawing: <UL> <PRE> void OptimizerWindow::draw() { @@ -330,7 +330,7 @@ void OptimizerWindow::draw() { context_->makeCurrent(fl_display, fl_window); #endif // WIN32 - ... perform other context setup as desired ... + ... perform other context setup as desired ... // Then create the draw action to handle drawing things... @@ -368,6 +368,6 @@ void OptimizerWindow::draw() { </PRE> </UL> <H4>The scene() Method</H4> - The <TT>scene()</TT> method sets the scene to be drawn. The scene is -a collection of 3D objects in a <TT>csGroup</TT>. The scene is redrawn + The <TT>scene()</TT> method sets the scene to be drawn. The scene is +a collection of 3D objects in a <TT>csGroup</TT>. The scene is redrawn after this call. </BODY></HTML> diff --git a/documentation/osissues.html b/documentation/osissues.html index 4eede262b..c52c1d615 100644 --- a/documentation/osissues.html +++ b/documentation/osissues.html @@ -1,56 +1,56 @@ <HTML><BODY> <H1 ALIGN=RIGHT><A NAME=osissues>F - Operating System Issues</A></H1> - This appendix describes the X and WIN32 specific interfaces in FLTK. + This appendix describes the X and WIN32 specific interfaces in FLTK. <H2>X-Specific Interface</H2> <UL> <PRE> #include <FL/x.H> </PRE> </UL> - On 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. + On 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. <H3>Handling Other X Events</H3> <H4><A name=add_handler>void Fl::add_handler(int (*f)(int))</A></H4> - Installs 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 + Installs 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><TT>fl_xevent</TT></A> variable. </P> -<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 +<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 example <TT>FL_SHORTCUT</TT>). </P> <H4><A name=fl_xevent>extern XEvent *fl_xvent</A></H4> - The most recent X event. + The most recent X event. <H4><A name=fl_event_time>extern ulong fl_event_time</A></H4> - 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. + 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. <H4><A name=fl_xid>Window fl_xid(const Fl_Window *)</A></H4> - Returns the XID for a window, or zero if not <TT>shown()</TT>. + Returns the XID for a window, or zero if not <TT>shown()</TT>. <H4><A name=fl_find>Fl_Window *fl_find(ulong xid)</A></H4> Returns the <TT>Fl_Window</TT> that corresponds to the given XID, or <TT> -NULL</TT> if not found. This uses a cache so it is slightly faster -than iterating through the windows yourself. +NULL</TT> if not found. This uses a cache so it is slightly faster +than iterating through the windows yourself. <H4><A name=fl_handle>int fl_handle(const XEvent &)</A></H4> - 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 <TT>add_handler()</TT> functions all ignore it this -returns false). + 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 <TT>add_handler()</TT> functions all ignore it this +returns false). <P>Besides feeding events your code should call <A href=functions.html#flush> <TT>Fl::flush()</TT></A> periodically so that FLTK redraws its windows. </P> -<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=functions.html#fl_ask><TT>fl_ask()</TT></A>, +<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=functions.html#fl_ask><TT>fl_ask()</TT></A>, for instance) it will not return until the modal function returns. </P> <H3>Drawing using Xlib</H3> The following global variables are set before <A HREF="subclassing.html#draw"><TT>Fl_Widget::draw()</TT></A> is called, or by <A href=Fl_Window.html#Fl_Window.make_current><TT> -Fl_Window::make_current()</TT></A>: +Fl_Window::make_current()</TT></A>: <UL> <PRE> extern Display *fl_display; @@ -61,69 +61,69 @@ extern XVisualInfo *fl_visual; extern Colormap fl_colormap; </PRE> </UL> - You must use them to produce Xlib calls. Don't attempt to change -them. A typical X drawing call is written like this: + You must use them to produce Xlib calls. Don't attempt to change +them. A typical X drawing call is written like this: <UL> <PRE> XDrawSomething(fl_display, fl_window, fl_gc, ...); </PRE> </UL> - Other information such as the position or size of the X window can be + Other information such as the position or size of the X window can be found by looking at <A href=Fl_Window.html#Fl_Window.make_current><TT> Fl_Window::current()</TT></A>, which returns a pointer to the <TT> -Fl_Window</TT> being drawn. +Fl_Window</TT> being drawn. <H4><A name=fl_xpixel>unsigned long fl_xpixel(Fl_Color i) <BR> unsigned long fl_xpixel(uchar r, uchar g, uchar b)</A></H4> - Returns the X pixel number used to draw the given FLTK color index or + Returns the X pixel number used to draw the given FLTK color index or RGB color. This is the X pixel that <A href="drawing.html#fl_color"><TT>fl_color()</TT> -</A> would use. +</A> would use. <H4><A name=fl_xfont>extern XFontStruct *fl_xfont</A></H4> Points at the font selected by the most recent <A href=drawing.html#fl_font> <TT>fl_font()</TT></A>. This is not necessarily the current font of <TT> fl_gc</TT>, which is not set until <A href="drawing.html#text"><TT>fl_draw()</TT></A> - is called. + is called. <H3>Changing the Display, Screen, or X Visual</H3> - FLTK uses only a single display, screen, X visual, and X colormap. -This greatly simplifies its internal structure and makes it much -smaller and faster. You can change which it uses by setting global -variables <I>before the first <TT>Fl_Window::show()</TT> is called</I>. + FLTK uses only a single display, screen, X visual, and X colormap. +This greatly simplifies its internal structure and makes it much +smaller and faster. You can change which it uses by setting global +variables <I>before the first <TT>Fl_Window::show()</TT> is called</I>. You may also want to call <A href=functions.html#visual>Fl::visual()</A> -, which is a portable interface to get a full color and/or double -buffered visual. +, which is a portable interface to get a full color and/or double +buffered visual. <H4><A name=display>int Fl::display(const char *)</A></H4> Set which X display to use. This actually does <TT> -putenv("DISPLAY=...")</TT> so that child programs will display on the -same screen if called with <TT>exec()</TT>. This must be done before -the display is opened. This call is provided under WIN32 but it has no -effect. +putenv("DISPLAY=...")</TT> so that child programs will display on the +same screen if called with <TT>exec()</TT>. This must be done before +the display is opened. This call is provided under WIN32 but it has no +effect. <H4><A name=fl_display>extern Display *fl_display</A></H4> - The open X display. This is needed as an argument to most Xlib calls. -Don't attempt to change it! This is <TT>NULL</TT> before the display -is opened. + The open X display. This is needed as an argument to most Xlib calls. +Don't attempt to change it! This is <TT>NULL</TT> before the display +is opened. <H4><A name=fl_open_display>void fl_open_display()</A></H4> - Opens the display. Does nothing if it is already open. This will -make sure <TT>fl_display</TT> 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 <TT>show()</TT> of a window. -<P>This may call <TT>Fl::abort()</TT> if there is an error opening the + Opens the display. Does nothing if it is already open. This will +make sure <TT>fl_display</TT> 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 <TT>show()</TT> of a window. +<P>This may call <TT>Fl::abort()</TT> if there is an error opening the display. </P> <H4><A name=fl_close_display>void fl_close_display()</A></H4> - 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. + 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. <H4><A name=fl_screen>extern int fl_screen</A></H4> Which screen number to use. This is set by <TT>fl_open_display()</TT> - 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 <TT>Fl::display()</TT> string to "host:0,#". + 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 <TT>Fl::display()</TT> string to "host:0,#". <H4><A name=fl_visual>extern XVisualInfo *fl_visual</A> <BR><A name=fl_colormap>extern Colormap fl_colormap</A></H4> - The visual and colormap that FLTK will use for all windows. These are -set by <TT>fl_open_display()</TT> to the default visual and colormap. - You can change them before calling <TT>show()</TT> on the first -window. Typical code for changing the default visual is: + The visual and colormap that FLTK will use for all windows. These are +set by <TT>fl_open_display()</TT> to the default visual and colormap. + You can change them before calling <TT>show()</TT> on the first +window. Typical code for changing the default visual is: <UL> <PRE> Fl::args(argc, argv); // do this first so $DISPLAY is set @@ -136,19 +136,19 @@ window->show(argc, argv); </PRE> </UL> <H3>Using a Subclass of Fl_Window for Special X Stuff</H3> - 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 <TT>draw()</TT> method that uses Xlib -(and/or OpenGL) calls only. -<P>FLTK can also manage XID's provided by other libraries or programs, + 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 <TT>draw()</TT> method that uses Xlib +(and/or OpenGL) 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> <P>To do this, you need to make a subclass of <A href=Fl_Window.html#Fl_Window> <TT>Fl_Window</TT></A> and override some of these virtual functions: </P> <H4>virtual void Fl_Window::show()</H4> - If the window is already <TT>shown()</TT> this must cause it to be -raised, this can usually be done by calling <TT>Fl_Window::show()</TT>. + If the window is already <TT>shown()</TT> this must cause it to be +raised, this can usually be done by calling <TT>Fl_Window::show()</TT>. If not <TT>shown()</TT> your implementation must call either <TT> -Fl_X::set_xid()</TT> or <TT>Fl_X::make_xid()</TT>. +Fl_X::set_xid()</TT> or <TT>Fl_X::make_xid()</TT>. <P>An example: </P> <UL> <PRE> @@ -168,29 +168,29 @@ void MyWindow::show() { </PRE> </UL> <H4>Fl_X *Fl_X::set_xid(Fl_Window *, Window xid)</H4> - Allocate a hidden structure called an <TT>Fl_X</TT>, put the XID into + Allocate a hidden structure called an <TT>Fl_X</TT>, put the XID into it, and set a pointer to it from the <TT>Fl_Window</TT>. This causes <TT> -Fl_Window::shown()</TT> to return true. -<H4>void Fl_X::make_xid(Fl_Window *, XVisualInfo *= fl_visual, Colormap +Fl_Window::shown()</TT> to return true. +<H4>void Fl_X::make_xid(Fl_Window *, XVisualInfo *= fl_visual, Colormap = fl_colormap)</H4> - This static method does the most onerous parts of creating an X -window, including setting the label, resize limitations, etc. It then -does <TT>Fl_X::set_xid()</TT> with this new window and maps the window. + This static method does the most onerous parts of creating an X +window, including setting the label, resize limitations, etc. It then +does <TT>Fl_X::set_xid()</TT> with this new window and maps the window. <H4>virtual void Fl_Window::flush()</H4> - This virtual function is called by <TT>Fl::flush()</TT> to update the -window. For FLTK's own windows it does this by setting the global + This virtual function is called by <TT>Fl::flush()</TT> to update the +window. For FLTK's own windows it does this by setting the global variables <TT>fl_window</TT> and <TT>fl_gc</TT> and then calling the <TT> -draw()</TT> 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 <TT>damage()</TT> calls +draw()</TT> 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 <TT>damage()</TT> calls done so far is in <TT>Fl_X::i(this)->region</TT>. If <TT>NULL</TT> then you should redraw the entire window. The undocumented function <TT> -fl_clip_region(XRegion)</TT> will initialize the FLTK clip stack with a +fl_clip_region(XRegion)</TT> will initialize the FLTK clip stack with a region or <TT>NULL</TT> for no clipping. You must set region to <TT> -NULL</TT> afterwards as <TT>fl_clip_region()</TT> now owns it and will +NULL</TT> afterwards as <TT>fl_clip_region()</TT> now owns it and will delete it when done. </P> -<P>If <TT>damage() FL_DAMAGE_EXPOSE</TT> then only X expose events have -happened. This may be useful if you have an undamaged image (such as a +<P>If <TT>damage() FL_DAMAGE_EXPOSE</TT> then only X expose events have +happened. This may be useful if you have an undamaged image (such as a backing buffer) around. </P> <P>Here is a sample where an undamaged image is kept somewhere: </P> <UL> @@ -204,11 +204,11 @@ void MyWindow::flush() { </PRE> </UL> <H4>virtual void Fl_Window::hide()</H4> - Destroy the window server copy of the window. Usually you will -destroy contexts, pixmaps, or other resources used by the window, and -then call <TT>Fl_Window::hide()</TT> to get rid of the main window -identified by <TT>xid()</TT>. If you override this, you must also -override the destructor as shown: + Destroy the window server copy of the window. Usually you will +destroy contexts, pixmaps, or other resources used by the window, and +then call <TT>Fl_Window::hide()</TT> to get rid of the main window +identified by <TT>xid()</TT>. If you override this, you must also +override the destructor as shown: <UL> <PRE> void MyWindow::hide() { @@ -223,7 +223,7 @@ void MyWindow::hide() { <H4>virtual void Fl_Window::~Fl_Window()</H4> Because of the way C++ works, if you override <TT>hide()</TT> you <I> must</I> override the destructor as well (otherwise only the base class <TT> -hide()</TT> is called): +hide()</TT> is called): <UL> <PRE> MyWindow::~MyWindow() { @@ -232,13 +232,13 @@ MyWindow::~MyWindow() { </PRE> </UL> <H3>Setting the Icon of a Window</H3> -FLTK currently supports setting a window's icon *before* it is shown -using the <TT>Fl_Window::icon()</TT> method. +FLTK currently supports setting a window's icon *before* it is shown +using the <TT>Fl_Window::icon()</TT> method. <H4>void Fl_Window::icon(char *)</H4> -Sets the icon for the window to the passed pointer. You will need to -cast the icon <TT>Pixmap</TT> to a <TT>char *</TT> when calling this -method. To set the icon using a bitmap compiled with your application -use: +Sets the icon for the window to the passed pointer. You will need to +cast the icon <TT>Pixmap</TT> to a <TT>char *</TT> when calling this +method. To set the icon using a bitmap compiled with your application +use: <UL> <PRE> #include "icon.xbm" @@ -260,45 +260,45 @@ window->icon((char *)p); #include <FL/x.H> </PRE> </UL> - The <TT><FL/x.H></TT> header file defines the interface to FLTK's -WIN32-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. + The <TT><FL/x.H></TT> header file defines the interface to FLTK's +WIN32-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. <H3>Handling Other WIN32 Messages</H3> By default a single WNDCLASSEX called "FLTK" is created. All <TT> Fl_Windows</TT> are of this class unless you use <TT>Fl_Window::xclass()</TT> . The window class is created the first time <TT>Fl_Window::show()</TT> - is called. -<P>You can probably combine FLTK with other libraries that make their + is called. +<P>You can probably combine FLTK with other libraries that make their own WIN32 window classes. The easiest way is to call <TT>Fl::wait()</TT> -, it will call <TT>DispatchMessage</TT> for all messages to the other -windows. If necessary you can let the other library take over (as long -as it calls <TT>DispatchMessage()</TT>), but you will have to arrange -for the function <TT>Fl::flush()</TT> to be called regularily so that -widgets are updated, timeouts are handled, and the idle functions are +, it will call <TT>DispatchMessage</TT> for all messages to the other +windows. If necessary you can let the other library take over (as long +as it calls <TT>DispatchMessage()</TT>), but you will have to arrange +for the function <TT>Fl::flush()</TT> to be called regularily so that +widgets are updated, timeouts are handled, and the idle functions are called. </P> <H4><A name=fl_msg>extern MSG fl_msg</A></H4> - The most recent message read by <TT>GetMessage</TT> (which is called -by <A href=functions.html#wait><TT>Fl::wait()</TT></A>. This may not -be the most recent message sent to an FLTK window, because silly WIN32 -calls the handle procedures directly for some events (sigh). + The most recent message read by <TT>GetMessage</TT> (which is called +by <A href=functions.html#wait><TT>Fl::wait()</TT></A>. This may not +be the most recent message sent to an FLTK window, because silly WIN32 +calls the handle procedures directly for some events (sigh). <H4><A name=WIN32.add_handler>void Fl::add_handler(int (*f)(int))</A></H4> - 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 <TT>DefWindowProc()</TT>. + 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 <TT>DefWindowProc()</TT>. <H4><A name=WIN32.fl_xid>HWND fl_xid(const Fl_Window *)</A></H4> Returns the window handle for a <TT>Fl_Window</TT>, or zero if not <TT> -shown()</TT>. +shown()</TT>. <H4><A name=WIN32.fl_find>Fl_Window *fl_find(HWND xid)</A></H4> - Return the <TT>Fl_Window</TT> that corresponds to the given window -handle, or <TT>NULL</TT> if not found. This uses a cache so it is -slightly faster than iterating through the windows yourself. + Return the <TT>Fl_Window</TT> that corresponds to the given window +handle, or <TT>NULL</TT> if not found. This uses a cache so it is +slightly faster than iterating through the windows yourself. <H3>Drawing Things Using the WIN32 GDI</H3> - When the virtual function <A HREF="subclassing.html#draw"><TT>Fl_Widget::draw()</TT></A> is called, FLTK -has stashed in some global variables all the silly extra arguments you -need to make a proper GDI call. These are: + When the virtual function <A HREF="subclassing.html#draw"><TT>Fl_Widget::draw()</TT></A> 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> <PRE> extern HINSTANCE fl_display; @@ -311,25 +311,25 @@ HBRUSH fl_brush(); </UL> These global variables are set before <TT>draw()</TT> is called, or by <A href=Fl_Window.html#Fl_Window.make_current><TT>Fl_Window::make_current()</TT> -</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 <TT>fl_color()</TT> and are created as needed and -cached. A typical GDI drawing call is written like this: +</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 <TT>fl_color()</TT> and are created as needed and +cached. A typical GDI drawing call is written like this: <UL> <PRE> DrawSomething(fl_gc, ..., fl_brush()); </PRE> </UL> It may also be useful to refer to <A href=Fl_Window.html#Fl_Window.make_current> -<TT>Fl_Window::current()</TT></A> to get the window's size or position. +<TT>Fl_Window::current()</TT></A> to get the window's size or position. <H3>Setting the Icon of a Window</H3> - FLTK currently supports setting a window's icon *before* it is shown -using the <TT>Fl_Window::icon()</TT> method. + FLTK currently supports setting a window's icon *before* it is shown +using the <TT>Fl_Window::icon()</TT> method. <H4>void Fl_Window::icon(char *)</H4> - Sets the icon for the window to the passed pointer. You will need to -cast the <TT>HICON</TT> handle to a <TT>char *</TT> when calling this -method. To set the icon using an icon resource compiled with your -application use: + Sets the icon for the window to the passed pointer. You will need to +cast the <TT>HICON</TT> handle to a <TT>char *</TT> when calling this +method. To set the icon using an icon resource compiled with your +application use: <UL> <PRE> window->icon((char *)LoadIcon(fl_display, MAKEINTRESOURCE(IDI_ICON))); @@ -344,33 +344,33 @@ specific resolutions or create the icon from bitmap data. <TT>Fl_Window::show()</TT> method does not bind the icon to the window. <H3>How to Not Get a MSDOS Console Window</H3> - WIN32 has a really stupid mode switch stored in the executables that -controls whether or not to make a console window. -<P>To always get a console window you simply create a console -application (the "/SUBSYSTEM:CONSOLE" option for the linker). For a -GUI-only application create a WIN32 application (the + WIN32 has a really stupid mode switch stored in the executables that +controls whether or not to make a console window. +<P>To always get a console window you simply create a console +application (the "/SUBSYSTEM:CONSOLE" option for the linker). For a +GUI-only application create a WIN32 application (the "/SUBSYSTEM:WINDOWS" option for the linker). </P> -<P>FLTK includes a <TT>WinMain()</TT> function that calls the ANSI -standard <TT>main()</TT> entry point for you. <I>This function creates +<P>FLTK includes a <TT>WinMain()</TT> function that calls the ANSI +standard <TT>main()</TT> entry point for you. <I>This function creates a console window when you use the debug version of the library.</I></P> <P>WIN32 applications without a console cannot write to <TT>stdout</TT> - or <TT>stderr</TT>, even if they are run from a console window. Any + or <TT>stderr</TT>, even if they are run from a console window. Any output is silently thrown away. </P> <H3>Known Bugs</H3> - If a program is deactivated, <TT>Fl::wait()</TT> 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 WIN32 and probably -impossible to get around. -<P><TT>Fl_Gl_Window::can_do_overlay()</TT> returns true until the first -time it attempts to draw an overlay, and then correctly returns whether + If a program is deactivated, <TT>Fl::wait()</TT> 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 WIN32 and probably +impossible to get around. +<P><TT>Fl_Gl_Window::can_do_overlay()</TT> returns true until the first +time it attempts to draw an overlay, and then correctly returns whether or not there is overlay hardware. </P> -<P>Cut text contains ^J rather than ^M^J to break lines. This is a +<P>Cut text contains ^J rather than ^M^J to break lines. This is a feature, not a bug. </P> -<P><TT>SetCapture</TT> (used by <TT>Fl::grab()</TT>) doesn't work, and +<P><TT>SetCapture</TT> (used by <TT>Fl::grab()</TT>) doesn't work, and the main window title bar turns gray while menus are popped up. </P> <P>FLUID does not support BMP files yet. </P> </BODY></HTML> diff --git a/documentation/preface.html b/documentation/preface.html index d6bd1952f..11f10a245 100644 --- a/documentation/preface.html +++ b/documentation/preface.html @@ -29,14 +29,14 @@ interfaces.</P> <LI><A HREF="common.html#common">Chapter 3 - Common Widgets and Attributes</A></LI> - <LI><A HREF="editor.html#editor">Chapter 4 - Designing a Simple Text + <LI><A HREF="editor.html#editor">Chapter 4 - Designing a Simple Text Editor</A></LI> <LI><A HREF="drawing.html#drawing">Chapter 5 - Drawing Things in FLTK</A></LI> <LI><A HREF="events.html#events">Chapter 6 - Handling Events</A></LI> - <LI><A HREF="subclassing.html#subclassing">Chapter 7 - Extending and + <LI><A HREF="subclassing.html#subclassing">Chapter 7 - Extending and Adding Widgets</A></LI> <LI><A HREF="opengl.html#opengl">Chapter 8 - Using OpenGL</A></LI> @@ -47,7 +47,7 @@ interfaces.</P> <LI><A HREF="functions.html#functions">Appendix B - Function Reference</A></LI> - <LI><A HREF="enumerations.html#enumerations">Appendix C - Enumeration + <LI><A HREF="enumerations.html#enumerations">Appendix C - Enumeration Reference</A></LI> <LI><A HREF="glut.html#glut">Appendix D - GLUT Compatibility</A></LI> @@ -92,12 +92,12 @@ interfaces.</P> <H2>Copyrights and Trademarks</H2> -<P>FLTK is Copyright 1998-2001 by Bill Spitzak and others. Use and -distribution of FLTK is governed by the GNU Library General Public +<P>FLTK is Copyright 1998-2001 by Bill Spitzak and others. Use and +distribution of FLTK is governed by the GNU Library General Public License, located in <A HREF="license.html#license">Appendix G</A>.</P> -<P>UNIX is a registered trademark of the X Open Group, Inc. Microsoft -and Windows are registered trademarks of Microsoft Corporation. OpenGL +<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. </P> </BODY> diff --git a/documentation/subclassing.html b/documentation/subclassing.html index ad2a1a6f0..9da68b134 100644 --- a/documentation/subclassing.html +++ b/documentation/subclassing.html @@ -1,51 +1,46 @@ <HTML><BODY> <H1 ALIGN=RIGHT><A NAME=subclassing>7 - Adding and Extending Widgets</A></H1> - This chapter describes how to add your own widgets or extend existing -widgets in FLTK. + This chapter describes how to add your own widgets or extend existing +widgets in FLTK. <H2>Subclassing</H2> - New widgets are created by <I>subclassing</I> an existing FLTK widget, -typically <TT>Fl_Widget</TT> for controls and <TT>Fl_Group</TT> for -composite widgets. -<P>A control widget typically interacts with the user to receive and/or + New widgets are created by <I>subclassing</I> an existing FLTK widget, +typically <TT>Fl_Widget</TT> for controls and <TT>Fl_Group</TT> for +composite widgets. +<P>A control widget typically interacts with the user to receive and/or display a value of some sort. </P> -<P>A composite widget widget holds a list of child widgets and handles moving, -sizing, showing, or hiding them as needed. <TT>Fl_Group</TT> is the +<P>A composite widget widget holds a list of child widgets and handles moving, +sizing, showing, or hiding them as needed. <TT>Fl_Group</TT> is the main composite widget widget class in FLTK, and all of the other composite widgets (<TT> -Fl_Pack</TT>, <TT>Fl_Scroll</TT>, <TT>Fl_Tabs</TT>, <TT>Fl_Tile</TT>, +Fl_Pack</TT>, <TT>Fl_Scroll</TT>, <TT>Fl_Tabs</TT>, <TT>Fl_Tile</TT>, and <TT>Fl_Window</TT>) are subclasses of it. </P> -<P>You can also subclass other existing widgets to provide a different -look or user-interface. For example, the button widgets are all -subclasses of <TT>Fl_Button</TT> since they all interact with the user -via a mouse button click. The only difference is the code that draws +<P>You can also subclass other existing widgets to provide a different +look or user-interface. For example, the button widgets are all +subclasses of <TT>Fl_Button</TT> since they all interact with the user +via a mouse button click. The only difference is the code that draws the face of the button. </P> <H2>Making a Subclass of Fl_Widget</H2> - Your subclasses can directly descend from <TT>Fl_Widget</TT> or any -subclass of <TT>Fl_Widget</TT>. <TT>Fl_Widget</TT> has only four -virtual methods, and overriding some or all of these may be necessary. + Your subclasses can directly descend from <TT>Fl_Widget</TT> or any +subclass of <TT>Fl_Widget</TT>. <TT>Fl_Widget</TT> has only four +virtual methods, and overriding some or all of these may be necessary. <H2>The Constructor</H2> - The constructor should have the following arguments: -<UL> -<PRE> + The constructor should have the following arguments: +<UL><PRE> MyClass(int x, int y, int w, int h, const char *label = 0); -</PRE> -</UL> +</PRE></UL> This will allow the class to be used in <A href=fluid.html#fluid>FLUID</A> - without problems. -<P>The constructor must call the constructor for the base class and + without problems. +<P>The constructor must call the constructor for the base class and pass the same arguments: </P> -<UL> -<PRE> +<UL><PRE> MyClass::MyClass(int x, int y, int w, int h, const char *label) : Fl_Widget(x, y, w, h, label) { // do initialization stuff... } -</PRE> -</UL> +</PRE></UL> <TT>Fl_Widget</TT>'s protected constructor sets <TT>x()</TT>, <TT>y()</TT>, -<TT>w()</TT>, <TT>h()</TT>, and <TT>label()</TT> to the passed values -and initializes the other instance variables to: -<UL> -<PRE> +<TT>w()</TT>, <TT>h()</TT>, and <TT>label()</TT> to the passed values +and initializes the other instance variables to: +<UL><PRE> type(0); box(FL_NO_BOX); color(FL_GRAY); @@ -57,14 +52,16 @@ labelcolor(FL_BLACK); align(FL_ALIGN_CENTER); callback(default_callback,0); flags(ACTIVE|VISIBLE); -</PRE> -</UL> +image(0); +deimage(0); +</PRE></UL> <H2>Protected Methods of Fl_Widget</H2> - The following methods are provided for subclasses to use: + The following methods are provided for subclasses to use: <UL> <LI><A href=#clear_visible><TT>Fl_Widget::clear_visible</TT></A></LI> <LI><A href=#damage><TT>Fl_Widget::damage</TT></A></LI> <LI><A href=#draw_box><TT>Fl_Widget::draw_box</TT></A></LI> +<LI><A href=#draw_focus><TT>Fl_Widget::draw_focus</TT></A></LI> <LI><A href=#draw_label><TT>Fl_Widget::draw_label</TT></A></LI> <LI><A href=#set_flag><TT>Fl_Widget::set_flag</TT></A></LI> <LI><A href=#set_visible><TT>Fl_Widget::set_visible</TT></A></LI> @@ -74,16 +71,16 @@ flags(ACTIVE|VISIBLE); <H4><A name=damage>void Fl_Widget::damage(uchar mask) <BR> void Fl_Widget::damage(uchar mask, int x, int y, int w, int h) <BR> uchar Fl_Widget::damage()</A></H4> -The first form indicates that a partial update of the object is +The first form indicates that a partial update of the object is needed. The bits in mask are OR'd into <TT>damage()</TT>. Your <TT> draw()</TT> routine can examine these bits to limit what it is drawing. The public method <TT>Fl_Widget::redraw()</TT> simply does <TT> Fl_Widget::damage(FL_DAMAGE_ALL)</TT>, but the implementation of -your widget can call the private <TT>damage(n)</TT>. -<P>The second form indicates that a region is damaged. If only these -calls are done in a window (no calls to <TT>damage(n)</TT>) 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 +your widget can call the private <TT>damage(n)</TT>. +<P>The second form indicates that a region is damaged. If only these +calls are done in a window (no calls to <TT>damage(n)</TT>) 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 <TT>damage()</TT> unless this is a <TT>Fl_Window</TT> widget. </P> <P>The third form returns the bitwise-OR of all <TT>damage(n)</TT> calls done since the last <TT>draw()</TT>.</P> @@ -111,83 +108,89 @@ MyClass::draw() { </PRE></UL> <H4><A name=draw_box>void Fl_Widget::draw_box() const <BR></A>void Fl_Widget::draw_box(Fl_Boxtype b, ulong c) const</H4> - The first form draws this widget's <TT>box()</TT>, using the -dimensions of the widget. The second form uses <TT>b</TT> as the box -type and <TT>c</TT> as the color for the box. + The first form draws this widget's <TT>box()</TT>, using the +dimensions of the widget. The second form uses <TT>b</TT> as the box +type and <TT>c</TT> as the color for the box. + +<H4><A name="draw_focus">void Fl_Widget::draw_focus() const +<BR>void Fl_Widget::draw_focus(Fl_Boxtype b, int x, int y, int w, int h) const</A></H4> + +<P>Draws a focus box inside the widgets bounding box. The second +form allows you to specify a different bounding box. + <H4><A name=draw_label>void Fl_Widget::draw_label() const <BR> void Fl_Widget::draw_label(int x, int y, int w, int h) const -<BR> void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Align +<BR> void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Align align) const</A></H4> - This is the usual function for a <TT>draw()</TT> 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). -<P>The second form uses the passed bounding box instead of the widget's -bounding box. This is useful so "centered" labels are aligned with some + This is the usual function for a <TT>draw()</TT> 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). +<P>The second form uses the passed bounding box instead of the widget's +bounding box. This is useful so "centered" labels are aligned with some feature, like a moving slider. </P> <P>The third form draws the label anywhere. It acts as though <TT> -FL_ALIGN_INSIDE</TT> has been forced on so the label will appear inside -the passed bounding box. This is designed for parent groups to draw +FL_ALIGN_INSIDE</TT> has been forced on so the label will appear inside +the passed bounding box. This is designed for parent groups to draw labels with. </P> <H4><A name=set_flag>void Fl_Widget::set_flag(SHORTCUT_LABEL)</A></H4> Modifies <TT>draw_label()</TT> so that '&' characters cause an underscore -to be printed under the next letter. +to be printed under the next letter. <H4><A name=set_visible>void Fl_Widget::set_visible()</A> <BR><A name=clear_visible>void Fl_Widget::clear_visible()</A></H4> Fast inline versions of <TT>Fl_Widget::hide()</TT> and <TT> Fl_Widget::show()</TT>. These do not send the <TT>FL_HIDE</TT> and <TT> -FL_SHOW</TT> events to the widget. +FL_SHOW</TT> events to the widget. <H4><A name=test_shortcut>int Fl_Widget::test_shortcut() const <BR> static int Fl_Widget::test_shortcut(const char *s)</A></H4> - The first version tests <TT>Fl_Widget::label()</TT> against the -current event (which should be a <TT>FL_SHORTCUT</TT> event). If the -label contains a '&' character and the character after it matches the key + The first version tests <TT>Fl_Widget::label()</TT> against the +current event (which should be a <TT>FL_SHORTCUT</TT> event). If the +label contains a '&' character and the character after it matches the key press, this returns true. This returns false if the <TT>SHORTCUT_LABEL</TT> -flag is off, if the label is <TT>NULL</TT> 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 against an arbitrary +flag is off, if the label is <TT>NULL</TT> 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 against an arbitrary string. </P> <H4><A name=type>uchar Fl_Widget::type() const <BR> void Fl_Widget::type(uchar t)</A></H4> - The property <TT>Fl_Widget::type()</TT> can return an arbitrary 8-bit + The property <TT>Fl_Widget::type()</TT> can return an arbitrary 8-bit identifier, and can be set with the protected method <TT>type(uchar t)</TT> -. This value had to be provided for Forms compatibility, 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 +. This value had to be provided for Forms compatibility, 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> -<P>If you don't have RTTI you can use the clumsy FLTK mechanisim, by -having <TT>type()</TT> use a unique value. These unique values must -be greater than the symbol <TT>FL_RESERVED_TYPE</TT> (which is 100). -Look through the header files for <TT>FL_RESERVED_TYPE</TT> to find an +<P>If you don't have RTTI you can use the clumsy FLTK mechanisim, by +having <TT>type()</TT> use a unique value. These unique values must +be greater than the symbol <TT>FL_RESERVED_TYPE</TT> (which is 100). +Look through the header files for <TT>FL_RESERVED_TYPE</TT> to find an unused number. If you make a subclass of <TT>Fl_Window</TT> -you must use <TT>FL_WINDOW + n</TT> (<TT>n</tt> must be in the +you must use <TT>FL_WINDOW + n</TT> (<TT>n</tt> must be in the range 1 to 7). </P> <H2><A NAME="handle">Handling Events</A></H2> - The virtual method <TT>int Fl_Widget::handle(int event)</TT> is called -to handle each event passed to the widget. It can: + The virtual method <TT>int Fl_Widget::handle(int event)</TT> is called +to handle each event passed to the widget. It can: <UL> <LI>Change the state of the widget. </LI> <LI>Call <A href=Fl_Widget.html#Fl_Widget.redraw><TT>Fl_Widget::redraw()</TT> </A> if the widget needs to be redisplayed. </LI> <LI>Call <A href=Fl_Widget.html#Fl_Widget.damage><TT> -Fl_Widget::damage(n)</TT></A> if the widget needs a partial-update +Fl_Widget::damage(n)</TT></A> if the widget needs a partial-update (assuming you provide support for this in your <A HREF="#draw"><TT>Fl_Widget::draw()</TT></A> method). </LI> <LI>Call <A href=Fl_Widget.html#Fl_Widget.do_callback><TT> Fl_Widget::do_callback()</TT></A> if a callback should be generated. </LI> <LI>Call <TT>Fl_Widget::handle()</TT> on child widgets. </LI> </UL> - Events are identified by the integer argument. Other information -about the most recent event is stored in static locations and aquired + Events are identified by the integer argument. Other information +about the most recent event is stored in static locations and aquired by calling the <A href=events.html#events><TT>Fl::event_*()</TT></A> - functions. This information remains valid until another event is -handled. -<P>Here is a sample <TT>handle()</TT> method for a widget that acts as + functions. This information remains valid until another event is +handled. +<P>Here is a sample <TT>handle()</TT> method for a widget that acts as a pushbutton and also accepts the keystroke 'x' to cause the callback: </P> -<UL> -<PRE> +<UL><PRE> int MyClass::handle(int event) { switch(event) { case FL_PUSH: @@ -221,63 +224,66 @@ int MyClass::handle(int event) { return Fl_Widget::handle(event); } } -</PRE> -</UL> - You must return non-zero if your <TT>handle()</TT> method uses the -event. If you return zero it indicates to the parent widget that it can -try sending the event to another widget. +</PRE></UL> + +<P>You must return non-zero if your <TT>handle()</TT> method +uses the event. If you return zero, the parent widget will try +sending the event to another widget. + <H2><A NAME="draw">Drawing the Widget</A></H2> - The <TT>draw()</TT> virtual method is called when FLTK wants you to -redraw your widget. It will be called if and only if <TT>damage()</TT> - is non-zero, and <TT>damage()</TT> will be cleared to zero after it -returns. <TT>draw()</TT> should be declared protected, so that it can't -be called from non-drawing code. -<P><TT>damage()</TT> contains the bitwise-OR of all the <TT>damage(n)</TT> - 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 on the <TT>FL_DAMAGE_ALL</TT> bit if it thinks the entire widget -must be redrawn (e.g. for an expose event). </P> + +<P>The <TT>draw()</TT> virtual method is called when FLTK wants +you to redraw your widget. It will be called if and only if +<TT>damage()</TT> is non-zero, and <TT>damage()</TT> will be +cleared to zero after it returns. The <TT>draw()</TT> method +should be declared protected so that it can't be called from +non-drawing code. + +<P>The <TT>damage()</TT> value contains the bitwise-OR of all +the <TT>damage(n)</TT> 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 on the +<TT>FL_DAMAGE_ALL</TT> bit if it thinks the entire widget must +be redrawn, e.g. for an expose event. </P> + <P>Expose events (and the above <TT>damage(b,x,y,w,h)</TT>) will cause <TT> draw()</TT> to be called with FLTK's <A href=drawing.html#clipping> -clipping</A> turned on. You can greatly speed up redrawing in some -cases by testing <TT>fl_not_clipped(x,y,w,h)</TT> or <TT>fl_clip_box(...)</TT> and +clipping</A> turned on. You can greatly speed up redrawing in some +cases by testing <TT>fl_not_clipped(x,y,w,h)</TT> or <TT>fl_clip_box(...)</TT> and skipping invisible parts. </P> -<P>Besides the protected methods described above, FLTK provides a large +<P>Besides the protected methods described above, FLTK provides a large number of basic drawing functions, which are described <A href=drawing.html#drawing> below</A>. </P> <H2>Resizing the Widget</H2> - The <TT>resize(int x, int y, int w, int h)</TT> method is called when -the widget is being resized or moved. The arguments are the new -position, width, and height. <TT>x()</TT>, <TT>y()</TT>, <TT>w()</TT>, + The <TT>resize(int x, int y, int w, int h)</TT> method is called when +the widget is being resized or moved. The arguments are the new +position, width, and height. <TT>x()</TT>, <TT>y()</TT>, <TT>w()</TT>, and <TT>h()</TT> still remain the old size. You must call <TT>resize()</TT> - on your base class with the same arguments to get the widget size to -actually change. + on your base class with the same arguments to get the widget size to +actually change. <P>This should <I>not</I> call <TT>redraw()</TT>, at least if only the <TT> x()</TT> and <TT>y()</TT> change. This is because composite widgets like <A href=Fl_Scroll.html#Fl_Scroll> -<TT>Fl_Scroll</TT></A> may have a more efficient way of drawing the new +<TT>Fl_Scroll</TT></A> may have a more efficient way of drawing the new position. </P> <H2>Making a Composite Widget</H2> A "composite" widget contains one or more "child" widgets. To make a composite widget you should subclass <A href=Fl_Group.html#Fl_Group><TT>Fl_Group</TT></A> . It is possible to make a composite object that is not a subclass of <TT> Fl_Group</TT>, but you'll have to duplicate the code in <TT>Fl_Group</TT> - anyways. + anyways. <P>Instances of the child widgets may be included in the parent: </P> -<UL> -<PRE> +<UL><PRE> class MyClass : public Fl_Group { Fl_Button the_button; Fl_Slider the_slider; ... }; -</PRE> -</UL> - The constructor has to initialize these instances. They are +</PRE></UL> + The constructor has to initialize these instances. They are automatically <TT>add()</TT>ed to the group, since the <TT>Fl_Group</TT> constructor does <TT>begin()</TT>. <I>Don't forget to call <TT>end()</TT> or use the <A href=Fl_End.html#Fl_End><TT>Fl_End</TT></A> pseudo-class:</I> -<UL> -<PRE> +<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), @@ -286,41 +292,38 @@ MyClass::MyClass(int x, int y, int w, int h) : ...(you could add dynamically created child widgets here)... end(); // don't forget to do this! } -</PRE> -</UL> - The child widgets need callbacks. These will be called with a pointer +</PRE></UL> + The child widgets need callbacks. These will be called with a pointer to the children, but the widget itself may be found in the <TT>parent()</TT> - 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 + pointer of the child. Usually these callbacks can be static private +methods, with a matching private method: +<UL><PRE> +void MyClass::static_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> - If you make the <TT>handle()</TT> method, you can quickly pass all the -events to the children using the <TT>Fl_Group::handle()</TT> method. +</PRE></UL> + If you make the <TT>handle()</TT> method, you can quickly pass all the +events to the children using the <TT>Fl_Group::handle()</TT> method. You don't need to override <TT>handle()</TT> if your composite widget -does nothing other than pass events to the children: -<UL> -<PRE> +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> - If you override <TT>draw()</TT> you need to draw all the children. If <TT> -redraw()</TT> or <TT>damage()</TT> is called on a child, <TT> -damage(FL_DAMAGE_CHILD)</TT> is done to the group, so this bit of <TT> -damage()</TT> 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> +</PRE></UL> + +<P>If you override <TT>draw()</TT> you need to draw all the +children. If <TT>redraw()</TT> or <TT>damage()</TT> is called +on a child, <TT>damage(FL_DAMAGE_CHILD)</TT> is done to the +group, so this bit of <TT>damage()</TT> 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() == FL_DAMAGE_CHILD) { // only redraw some children @@ -330,14 +333,13 @@ int MyClass::draw() { // 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 + draw_outside_label(**a); // you may not need to do this } } } -</PRE> -</UL> -<TT>Fl_Group</TT> provides some protected methods to make drawing -easier: +</PRE></UL> +<TT>Fl_Group</TT> provides some protected methods to make drawing +easier: <UL> <LI><A href=#draw_child>draw_child</A></LI> <LI><A href=#draw_outside_label>draw_outside_label</A></LI> @@ -345,51 +347,66 @@ easier: </UL> <H4><A name=draw_child>void Fl_Group::draw_child(Fl_Widget&)</A></H4> This will force the child's <TT>damage()</TT> bits all to one and call <TT> -draw()</TT> on it, then clear the <TT>damage()</TT>. 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 <TT>visible()</TT> or if it is -clipped. -<H4><A name=draw_outside_label>void +draw()</TT> on it, then clear the <TT>damage()</TT>. 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 <TT>visible()</TT> or if it is +clipped. +<H4><A name=draw_outside_label>void Fl_Group::draw_outside_label(Fl_Widget&) const</A></H4> Draw the labels that are <I>not</I> drawn by <A href=#draw_label><TT> -draw_label()</TT></A>. If you want more control over the label -positions you might want to call <TT>child->draw_label(x,y,w,h,a)</TT>. +draw_label()</TT></A>. If you want more control over the label +positions you might want to call <TT>child->draw_label(x,y,w,h,a)</TT>. <H4><A name=update_child>void Fl_Group::update_child(Fl_Widget&)</A></H4> - Draws the child only if its <TT>damage()</TT> is non-zero. You -should call this on all the children if your own damage is equal to + Draws the child only if its <TT>damage()</TT> is non-zero. You +should call this on all the children if your own damage is equal to FL_DAMAGE_CHILD. Nothing is done if the child is not <TT>visible()</TT> - or if it is clipped. + or if it is clipped. <H2>Cut and Paste Support</H2> - FLTK provides routines to cut and paste 8-bit text (in the future this -may be UTF-8) between applications: +FLTK provides routines to cut and paste 8-bit text (in the future this +may be UTF-8) between applications: <UL> -<LI><A href=functions.html#paste><TT>Fl::paste</TT></A></LI> -<LI><A href=functions.html#selection><TT>Fl::selection</TT></A></LI> -<LI><A href=functions.html#selection_length><TT>Fl::selection_length</TT></A></LI> -<LI><A href=functions.html#selection_owner><TT>Fl::selection_owner</TT></A></LI> +<LI><A href="Fl.html#Fl.paste"><TT>Fl::paste</TT></A></LI> +<LI><A href="Fl.html#Fl.selection"><TT>Fl::selection</TT></A></LI> +<LI><A href="Fl.html#Fl.selection_length"><TT>Fl::selection_length</TT></A></LI> +<LI><A href="Fl.html#Fl.selection_owner"><TT>Fl::selection_owner</TT></A></LI> </UL> It may be possible to cut/paste non-text data by using <A href=osissues.html#add_handler> -<TT>Fl::add_handler()</TT></A>. +<TT>Fl::add_handler()</TT></A>. <H2>Making a subclass of Fl_Window</H2> -You may want your widget to be a subclass of <TT>Fl_Window</TT>. 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 <TT>Fl_Window </TT>is almost exactly like subclassing <TT> -Fl_Widget</TT>, and in fact you can easily switch a subclass back and -forth. Watch out for the following differences: </P> + +<P>You may want your widget to be a subclass of +<TT>Fl_Window</TT>, <TT>Fl_Double_Window</TT>, or +<TT>FL_Gl_Window</TT>. 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 <TT>Fl_Window</TT>is almost exactly like +subclassing <TT>Fl_Group</TT>, and in fact you can easily +switch a subclass back and forth. Watch out for the following +differences: </P> + <OL> -<LI><TT>Fl_Window</TT> is a subclass of <TT>Fl_Group</TT> so <I>make -sure your constructor calls <TT>end()</TT></I> (unless you actually -want children added to your window). </LI> -<LI>When handling events and drawing, the upper-left corner is at 0,0, -not <TT>x(),y()</TT> as in other <TT>Fl_Widget</TT>'s. For instance, to -draw a box around the widget, call <TT>draw_box(0, 0, w(), h())</TT>, -rather than <TT>draw_box(x(), y(), w(), h())</TT>. </LI> + + <LI><TT>Fl_Window</TT> is a subclass of + <TT>Fl_Group</TT> so <I>make sure your constructor calls + <TT>end()</TT></I> unless you actually want children + added to your window.</LI> + + <LI>When handling events and drawing, the upper-left + corner is at 0,0, not <TT>x(),y()</TT> as in other + <TT>Fl_Widget</TT>'s. For instance, to draw a box + around the widget, call <TT>draw_box(0, 0, w(), + h())</TT>, rather than <TT>draw_box(x(), y(), w(), + h())</TT>.</LI> + </OL> - You may also want to subclass <TT>Fl_Window</TT> in order to get -access to different visuals or to change other attributes of the -windows. See <A href=osissues.html#osissues>"Appendix F - Operating -System Issues"</A> for more information. </BODY></HTML> + +<P>You may also want to subclass <TT>Fl_Window</TT> in order to +get access to different visuals or to change other attributes of +the windows. See <A href="osissues.html">"Appendix F - Operating +System Issues"</A> for more information. + +</BODY> +</HTML> diff --git a/documentation/widgets.html b/documentation/widgets.html index 159913ca5..a3932e34b 100644 --- a/documentation/widgets.html +++ b/documentation/widgets.html @@ -1,7 +1,7 @@ <HTML><BODY> <H1 ALIGN=RIGHT><A NAME=widgets>A - Widget Reference</A></H1> -This appendix describes all of the classes in FLTK. For a +This appendix describes all of the classes in FLTK. For a description of the <TT>fl_</TT> functions, see <A href="functions.html">Appendix B</A>. |