diff --git a/documentation/Fl_Adjuster.html b/documentation/Fl_Adjuster.html index d7cdf0a90..bb51e26c1 100644 --- a/documentation/Fl_Adjuster.html +++ b/documentation/Fl_Adjuster.html @@ -1,61 +1,47 @@ - - - -
- -

class Fl_Adjuster

- -
- -

Class Hierarchy

- - +

Include Files

+ +

Description

+ The Fl_Adjuster widget was stolen from Prisms, and has proven +to be very useful for values that need a large dynamic range. When you +press a button and drag to the right the value increases. When you drag +to the left it decreases. The largest button adjusts by 100 * +step(), the next by 10 * step() and that smallest button +by step(). Clicking on the buttons increments by 10 times the +amount dragging by a pixel does. Shift + click decrements by 10 times +the amount. +

Methods

+ +

Fl_Adjuster::Fl_Adjuster(int x, int +y, int w, int h, const char *label = 0)

+ Creates a new Fl_Adjuster widget using the given position, +size, and label string. It looks best if one of the dimensions is 3 +times the other. +

virtual Fl_Adjuster::~Fl_Adjuster() +

+ Destroys the valuator. +

uchar Fl_Adjuster::soft() const +
void Fl_Adjuster::soft(uchar)

+ 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. \ No newline at end of file diff --git a/documentation/Fl_Box.html b/documentation/Fl_Box.html index e702d863d..4aa5cffeb 100644 --- a/documentation/Fl_Box.html +++ b/documentation/Fl_Box.html @@ -1,52 +1,39 @@ - - - -
- -

class Fl_Box

- -
- -

Class Hierarchy

- - +

Include Files

+ +

Description

+ 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. +

Methods

+ +

Fl_Box::Fl_Box(int x, int y, int w, int h, +const char * = 0) +
Fl_Box::Fl_Box(Fl_Boxtype b, int x, int y, int w, int h, const +char *)

+ The first constructor sets box() to FL_NO_BOX, which +means it is invisible. However such widgets are useful as placeholders +or Fl_Group::resizable() + values. To change the box to something visible, use box(n). +

The second form of the constructor sets the box to the specified box +type.

+

Fl_Box::~Fl_Box(void)

+ The destructor removes the box. \ No newline at end of file diff --git a/documentation/Fl_Browser.html b/documentation/Fl_Browser.html index c0219955c..cfd6c9ba8 100644 --- a/documentation/Fl_Browser.html +++ b/documentation/Fl_Browser.html @@ -1,276 +1,200 @@ - - - -
- -

class Fl_Browser

- -
- -

Class Hierarchy

- - +

Include Files

+ +

Description

+ The Fl_Browser 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. +

Each line in the browser is identified by number. The numbers +start at one (this is so that zero can be reserved for "no line" in +the selective browsers). 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 <= size().

+

Each line contains a null-terminated string of text and a void * + data pointer. The text string is displayed, the void * + pointer can be used by the callbacks to reference the object the text +describes.

+

The base class does nothing when the user clicks on it. The +subclasses +Fl_Select_Browser, +Fl_Hold_Browser, and +Fl_Multi_Browser react to user clicks to select lines in +the browser and do callbacks.

+

The base class called +Fl_Browser_ 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 Fl_Browser_ + 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 Fl_Browser_.

+

Methods

+
+ + +
+ + + + + + + + + +
+
+

Fl_Browser::Fl_Browser(int, int, int, +int, const char * = 0)

+ The constructor makes an empty browser. +

Fl_Browser::~Fl_Browser(void)

+ The destructor deletes all list items and destroys the browser. +

void Fl_Browser::add(const char *, void * = +0)

+ Add a new line to the end of the browser. The text is copied using +the strdup() function. It may also be NULL to make a +blank line. The void * argument is returned as the data() + of the new item. +

void Fl_Browser::clear()

+ Remove all the lines in the browser. +

uchar Fl_Browser::column_char() const +
void Fl_Browser::column_char(char c)

+ The first form gets the current column separator character. By default +this is '\t' (tab). +

The second form sets the column separator to c. This will +only have an effect if you also set column_widths().

+

const int +*Fl_Browser::column_widths() const +
void Fl_Browser::column_widths(const int *w)

+ 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 column_char() and each part is formatted +into it's own column. After the last column any remaining text is +formatted into the space between the last column and the right edge of +the browser, even if the text contains instances of column_char() +. The default value is a one-element array of just a zero, which makes +there are no columns. +

The second form sets the current array to w. Make sure the +last entry is zero.

+

void *Fl_Browser::data(int n) const +
void Fl_Browser::data(int n, void *)

+ The first form returns the data for line n. If n is +out of range this returns NULL. +

The second form sets the data for line n.

+

uchar Fl_Browser::format_char() const +
void Fl_Browser::format_char(char c)

+ The first form gets the current format code prefix character, which by +default is @. A string of formatting codes at the start of +each column are stripped off and used to modify how the rest of the +line is printed: + + Notice that the @. command can be used to reliably +terminate the parsing. To print a random string in a random color, use +sprintf("@C%d@.%s", color, string) and it will work even if the +string starts with a digit or has the format character in it. +

The second form sets the current prefix to c. Set the +prefix to 0 to disable formatting.

+

void Fl_Browser::hide(int n)

+ Makes line n invisible, preventing selection by the user. + The line can still be selected under program control. +

void Fl_Browser::insert(int n, const char +*, void * = 0)

+ Insert a new line before line n. If n > +size() then the line is added to the end. +

int Fl_Browser::load(const char *filename) +

+ Clears the browser and reads the file, adding each line from the file +to the browser. If the filename is NULL 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 errno + is set to the system error. The data() of each line is set +to NULL. +

void Fl_Browser::move(int to, int from)

+ Line from is removed and reinserted at to; to + is calculated after the line is removed. +

int Fl_Browser::position() const +
void Fl_Browser::position(int p)

+ 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. +

void Fl_Browser::remove(int n)

+ Remove line n and make the browser one line shorter. +

void Fl_Browser::show(int n)

+ Makes line n visible for selection. +

int Fl_Browser::size() const

+ Returns how many lines are in the browser. The last line number is +equal to this. +

const char *Fl_Browser::text(int n) const +
void Fl_Browser::text(int n, const char *)

+ The first form returns the text for line n. If n is +out of range it returns NULL. +

The second form sets the text for line n.

+

int Fl_Browser::topline() const +
void Fl_Browser::topline(int n)

+ The first form returns the current top line in the browser. If there +is no vertical scrollbar then this will always return 1. +

The second form sets the top line in the browser to n.

+

The second form sets the vertical scrollbar position to p.

+

int Fl_Browser::visible(int n) const

+ Returns a non-zero value if line n is visible. \ No newline at end of file diff --git a/documentation/Fl_Browser_.html b/documentation/Fl_Browser_.html index fc8456f51..037fd211f 100644 --- a/documentation/Fl_Browser_.html +++ b/documentation/Fl_Browser_.html @@ -1,171 +1,134 @@ - - - -
- -

class Fl_Browser_

- -
- -

Class Hierarchy

- - +

Include Files

+ +

Description

+ 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. +

This has been designed so that the subclass has complete control +over the storage of the data, although because next() and +prev() 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.

+

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 stat() on a file or doing some +other slow operation.

+

Methods

+
+ + +
+ + + + + + + + + +
+
+

Fl_Browser::Fl_Browser(int, int, +int, int, const char * = 0)

+ The constructor makes an empty browser. +

Fl_Browser::~Fl_Browser(void)

+ The destructor deletes all list items and destroys the browser. +

void +Fl_Browser_::has_scrollbar(int h)

+ 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 h: + +

Fl_Color Fl_Browser_::textcolor() +const +
void Fl_Browser_::textcolor(Fl_Color color)

+ The first form gets the default text color for the lines in the +browser. +

The second form sets the default text color to color

+

Fl_Font Fl_Browser_::textfont() const +
void Fl_Browser_::textfont(Fl_Font font)

+ The first form gets the default text font for the lines in the +browser. +

The second form sets the default text font to font

+

uchar Fl_Browser_::textsize() const +
void Fl_Browser_::textsize(uchar size)

+ The first form gets the default text size for the lines in the +browser. +

The second form sets the default text size to size

+ \ No newline at end of file diff --git a/documentation/Fl_Button.html b/documentation/Fl_Button.html index 3ed301853..f0bb3fd67 100644 --- a/documentation/Fl_Button.html +++ b/documentation/Fl_Button.html @@ -1,176 +1,130 @@ - - - -
- -

class Fl_Button

- -
- -

Class Hierarchy

- - +

Include Files

+ +

Description

+

Buttons generate callbacks when they are clicked by the user. You +control exactly when and how by changing the values for type() + and when().

+

Buttons can also generate callbacks in response to FL_SHORTCUT + events. The button can either have an explicit +shortcut() value or a letter shortcut can be indicated in +the label() with an ''character before it. For the label +shortcut it does not matter if Alt is held down, but if you have +an input field in the same window, the user will have to hold down the +Alt key so that the input field does not eat the event first as an +FL_KEYBOARD event.

+

Methods

+
+ + +
+ + + + + + + + + +
+
+

Fl_Button::Fl_Button(int x, int y, int +w, int h, const char *label = 0)

+ The constructor creates the button using the position, size, and +label. +

Fl_Button::~Fl_Button(void)

+ The destructor removed the button. +

int Fl_Button::clear()

+ Same as value(0). +

Fl_Boxtype Fl_Button::down_box() const +
void Fl_Button::down_box(Fl_Boxtype bt)

+ The first form returns the current down box type, which is drawn when +value() is non-zero. +

The second form sets the down box type. The default value of 0 +causes FLTK to figure out the correct matching down version of box() +.

+

int Fl_Button::set()

+ Same as value(1). +

void Fl_Button::setonly()

+ Turns on this button and turns off all other radio buttons in the +group (calling value(1) or set() does not do this). +

ulong Fl_Button::shortcut() const +
void Fl_Button::shortcut(ulong key)

+ The first form returns the current shortcut key for the button. +

The second form sets the shortcut key to key. Setting this +overrides the use of ''in the label(). The value is a bitwise +OR of a key and a set of shift flags, for example FL_ALT | 'a' +, FL_ALT | (FL_F + 10), or just 'a'. A value +of 0 disables the shortcut.

+

The key can be any value returned by +Fl::event_key(), but will usually be an ASCII letter. Use +a lower-case letter unless you require the shift key to be held down.

+

The shift flags can be any set of values accepted by +Fl::event_state(). 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).

+

uchar Fl_Button::type() const +
void Fl_Button::type(uchar t)

+ The first form of type() returns the current button type, +which can be one of: + + The second form sets the button type to t. +

char Fl_Button::value() const +
int Fl_Button::value(int)

+ The first form returns the current value (0 or 1). The second form +sets the current value. +

Fl_When Fl_Widget::when() const +
void Fl_Widget::when(Fl_When w)

+ Controls when callbacks are done. The following values are useful, +the default value is FL_WHEN_RELEASE: + + \ No newline at end of file diff --git a/documentation/Fl_Chart.html b/documentation/Fl_Chart.html index 5a9d527ab..83c6834eb 100644 --- a/documentation/Fl_Chart.html +++ b/documentation/Fl_Chart.html @@ -1,162 +1,119 @@ - - - -
- -

class Fl_Chart

- -
- -

Class Hierarchy

- - +

Include Files

+ +

Description

+ This widget displays simple charts and is provided for forms +compatibility. +

Methods

+
+ + +
+ + + + + + + + + +
+
+

Fl_Chart::Fl_Chart(int x, int y, int w, +int h, const char *label = 0)

+ Creates a new Fl_Chart widget using the given position, size, +and label string. The default boxtype is FL_NO_BOX. +

virtual Fl_Chart::~Fl_Chart()

+ Destroys the Fl_Chart widget and all of its data. +

void add(double value, const char *label = +NULL, uchar color = 0)

+ The add method adds the value and optionally +label and color to the chart. +

uchar autosize(void) const +
void autosize(uchar onoff)

+ The autosize 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. +

The second form of autosize sets the auto-sizing property +to onoff.

+

void bounds(double *a, double *b) +
void bounds(double a, double b)

+ The bounds method gets or sets the lower and upper bounds of +the chart values to a and b respectively. +

void clear(void)

+ The clear method removes all values from the chart. +

void insert(int pos, double value, const +char *label = NULL, uchar color = 0)

+ The insert method inserts a data value at the given position +pos. Position 0 is the first data value. +

int maxsize(void) const +
void maxsize(int n)

+ The maxsize method gets or sets the maximum number of data +values for a chart. +

void replace(int pos, double value, const +char *label = NULL, uchar color = 0)

+ The replace method replaces data value pos with +value, label, and color. Position 0 is the +first data value. +

int size(void) const

+ The size method returns the number of data values in the +chart. +

uchar type() const +
void type(uchar t)

+ The first form of type() returns the current chart type. The +chart type can be one of the following:
-
FL_BAR_CHART
-
Each sample value is drawn as a vertical bar.
- -
FL_FILLED_CHART
-
The chart is filled from the bottom of the graph to the - sample values.
- -
FL_HORBAR_CHART
-
Each sample value is drawn as a horizontal bar.
- -
FL_LINE_CHART
-
The chart is drawn as a polyline with vertices at each - sample value.
- -
FL_PIE_CHART
-
A pie chart is drawn with each sample value being drawn - as a proportionate slice in the circle.
- -
FL_SPECIALPIE_CHART
-
Like FL_PIE_CHART, but the first slice is separated from - the pie.
- -
FL_SPIKE_CHART
-
Each sample value is drawn as a vertical line.
+
FL_BAR_CHART
+
Each sample value is drawn as a vertical bar.
+
FL_FILLED_CHART
+
The chart is filled from the bottom of the graph to the sample +values.
+
FL_HORBAR_CHART
+
Each sample value is drawn as a horizontal bar.
+
FL_LINE_CHART
+
The chart is drawn as a polyline with vertices at each sample +value.
+
FL_PIE_CHART
+
A pie chart is drawn with each sample value being drawn as a +proportionate slice in the circle.
+
FL_SPECIALPIE_CHART
+
Like FL_PIE_CHART, but the first slice is separated from the pie.
+
FL_SPIKE_CHART
+
Each sample value is drawn as a vertical line.
- -The second form of type() sets the chart type to t. - -
- - - + The second form of type() sets the chart type to t. +
+ \ No newline at end of file diff --git a/documentation/Fl_Check_Button.html b/documentation/Fl_Check_Button.html index 14ac7f0eb..9b013ea2a 100644 --- a/documentation/Fl_Check_Button.html +++ b/documentation/Fl_Check_Button.html @@ -1,53 +1,40 @@ - - - -
- -

class Fl_Check_Button

- -
- -

Class Hierarchy

- - +

Include Files

+ +

Description

+ Buttons generate callbacks when they are clicked by the user. You +control exactly when and how by changing the values for type() + and when(). +

The Fl_Check_Button 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 selection_color(), which +defaults to FL_RED.

+

Methods

+ +

+Fl_Check_Button::Fl_Check_Button(int x, int y, int w, int h, const char +*label = 0)

+ Creates a new Fl_Check_Button widget using the given +position, size, and label string. +

+Fl_Check_Button::~Fl_Check_Button()

+ The destructor deletes the check button. \ No newline at end of file diff --git a/documentation/Fl_Choice.html b/documentation/Fl_Choice.html index 96b4337dc..e6f52706a 100644 --- a/documentation/Fl_Choice.html +++ b/documentation/Fl_Choice.html @@ -1,110 +1,80 @@ - - - -
- -

class Fl_Choice

- -
- -

Class Hierarchy

- - +

Include Files

+ +

Description

+ This is a button that when pushed pops up a menu (or hierarchy of +menus) defined by an array of +Fl_Menu_Item objects. Motif calls this an OptionButton. +

The only difference between this and a +Fl_Menu_Button 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 Fl_Menu_Button methods are redescribed here in those +terms.

+

When the user picks an item off the menu the value() is set +to that item and then the callback is done.

+

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.

+

The menu will also pop up in response to shortcuts indicated by +putting a ''character in the label(). See +Fl_Button for a description of this.

+

Typing the shortcut() 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.

+

Methods

+ +

Fl_Choice::Fl_Choice(int x, int y, int +w, int h, const char *label = 0)

+ Creates a new Fl_Choice widget using the given position, +size, and label string. The default boxtype is FL_UP_BOX. +

The constructor sets menu() to NULL. See +Fl_Menu_ for the methods to set or change the menu.

+

virtual Fl_Choice::~Fl_Choice()

+ The destructor removes the Fl_Choice widget and all of its +menu items. +

int Fl_Choice::value() const +
int Fl_Choice::value(int) +
int Fl_Choice::value(const Fl_Menu *)

+ The value is the index into the Fl_Menu 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 redraw(). +

int Fl_Widget::changed() const

+ This value is true if the user picks a different value. It is +turned off by value() and just before doing a callback (the +callback can turn it back on if desired). +

void Fl_Widget::set_changed()

+ This method sets the changed() flag. +

void Fl_Widget::clear_changed()

+ This method clears the changed() flag. +

Fl_Boxtype Fl_Choice::down_box() const +
void Fl_Choice::down_box(Fl_Boxtype b)

+ The first form gets the current down box, which is used when the menu +is popped up. The default down box type is FL_DOWN_BOX The +second form sets the current down box type to b. \ No newline at end of file diff --git a/documentation/Fl_Clock.html b/documentation/Fl_Clock.html index e1da8a9e9..0ddb2a10b 100644 --- a/documentation/Fl_Clock.html +++ b/documentation/Fl_Clock.html @@ -1,78 +1,56 @@ - - - -
- -

class Fl_Clock

- -
- -

Class Hierarchy

- - +

Include Files

+ +

Description

+ This widget provides a round analog clock display and is provided for +Forms compatibility. It installs a 1-second timeout callback using +Fl::add_timeout(). +

Methods

+ +

Fl_Clock::Fl_Clock(int x, int y, int w, +int h, const char *label = 0)

+ Creates a new Fl_Clock widget using the given position, size, +and label string. The default boxtype is FL_NO_BOX. +

virtual Fl_Clock::~Fl_Clock()

+ The destructor also deletes all the children. 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 +Fl_Clock and all of it's children can be automatic (local) +variables, but you must declare the Fl_Clockfirst, so +that it is destroyed last. +

int Fl_Clock::hour() const

+ Returns the current hour (0 to 23). +

int Fl_Clock::minute() const

+ Returns the current minute (0 to 59). +

int Fl_Clock::second() const

+ Returns the current second (0 to 60, 60 = leap second). +

void Fl_Clock::value(ulong v) +
void Fl_Clock::value(int h, int m, int s) +
ulong Fl_Clock::value(void)

+ The first two forms of value set the displayed time to the +given UNIX time value or specific hours, minutes, and seconds. +

The third form of value returns the displayed time in +seconds since the UNIX epoch (January 1, 1970).

+ \ No newline at end of file diff --git a/documentation/Fl_Color_Chooser.html b/documentation/Fl_Color_Chooser.html index 5f9a0ed53..26b798c6b 100644 --- a/documentation/Fl_Color_Chooser.html +++ b/documentation/Fl_Color_Chooser.html @@ -1,103 +1,78 @@ - - - -
- -

class Fl_Color_Chooser

- -
- -

Class Hierarchy

- - +

Include Files

+ +

Description

+ The Fl_Color_Chooser 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 same rgb value, such as when saturation +or value is zero. +

Methods

+ +

+Fl_Color_Chooser::Fl_Color_Chooser(int x, int y, int w, int h, const +char *label = 0)

+ Creates a new Fl_Color_Chooser widget using the given +position, size, and label string. The recommended dimensions are +200x95. The color is initialized to black. +

virtual +Fl_Color_Chooser::~Fl_Color_Chooser()

+ The destructor removes the color chooser and all of its controls. +

double Fl_Color_Chooser::hue() const +

+ Return the current hue. 0 <= hue < 6. Zero is red, one is yellow, +two is green, etc. This value is convienent for the internal +calculations - some other systems consider hue to run from zero to one, +or from 0 to 360. +

double +Fl_Color_Chooser::saturation() const

+ Returns the saturation. 0 <= saturation <= 1. +

double Fl_Color_Chooser::value() +const

+ Returns the value/brightness. 0 <= value <= 1. +

double Fl_Color_Chooser::r() const

+ Returns the current red value. 0 <= r <= 1. +

double Fl_Color_Chooser::g() const

+ Returns the current green value. 0 <= g <= 1. +

double Fl_Color_Chooser::b() const

+ Returns the current blue value. 0 <= b <= 1. +

int Fl_Color_Chooser::rgb(double, +double, double)

+ 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). +

int +Fl_Color_Chooser::hsv(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. +

static void +Fl_Color_Chooser::hsv2rgb(double, double, double, double&, double&, +double&)

+ This static method converts HSV colors to RGB colorspace. +

static void +Fl_Color_Chooser::rgb2hsv(double, double, double, double&, double&, +double&)

+ This static method converts RGB colors to HSV colorspace. + \ No newline at end of file diff --git a/documentation/Fl_Counter.html b/documentation/Fl_Counter.html index 42551fefa..d7832f9c2 100644 --- a/documentation/Fl_Counter.html +++ b/documentation/Fl_Counter.html @@ -1,66 +1,47 @@ - - - -
- -

class Fl_Counter

- -
- -

Class Hierarchy

- - +

Include Files

+ +

Description

+ The Fl_Counter widget is provided for forms compatibility. + It controls a single floating point value. +

Methods

+ +

Fl_Counter::Fl_Counter(int x, int y, +int w, int h, const char *label = 0)

+ Creates a new Fl_Counter widget using the given position, +size, and label string. The default type is FL_NORMAL_COUNTER. +

virtual Fl_Counter::~Fl_Counter()

+ Destroys the valuator. +

double Fl_Counter::lstep() const +
void Fl_Counter::lstep(double)

+ Get or set the increment for the double-arrow buttons. The default +value is 1.0. +

type(uchar)

+ Sets the type of counter: + + \ No newline at end of file diff --git a/documentation/Fl_Dial.html b/documentation/Fl_Dial.html index 2e732440a..ff70b6db1 100644 --- a/documentation/Fl_Dial.html +++ b/documentation/Fl_Dial.html @@ -1,65 +1,45 @@ - - - -
- -

class Fl_Dial

- -
- -

Class Hierarchy

- - +

Include Files

+ +

Description

+ The Fl_Dial widget provides a circular dial to control a +single floating point value. +

Methods

+ +

Fl_Dial::Fl_Dial(int x, int y, int w, int +h, const char *label = 0)

+ Creates a new Fl_Dial widget using the given position, size, +and label string. The default type is FL_NORMAL_DIAL. +

virtual Fl_Dial::~Fl_Dial()

+ Destroys the valuator. +

void Fl_Dial::angles(short a, short b)

+ Sets the angles used for the minimum and maximum values. By default +these are 0 and 360, respectively. +

type(uchar)

+ Sets the type of the dial to: + + \ No newline at end of file diff --git a/documentation/Fl_Double_Window.html b/documentation/Fl_Double_Window.html index 9018b850c..ffe154f76 100644 --- a/documentation/Fl_Double_Window.html +++ b/documentation/Fl_Double_Window.html @@ -1,66 +1,58 @@ - - - -
- -

class Fl_Double_Window

- -
- -

Class Hierarchy

- - - -
  • FL_HELVETICA - Helvetica (or Arial) normal. - -
  • FL_HELVETICA_BOLD - Helvetica (or Arial) bold. - -
  • FL_HELVETICA_ITALIC - Helvetica (or Arial) oblique. - -
  • FL_HELVETICA_BOLD_ITALIC - Helvetica (or Arial) bold-oblique. - -
  • FL_COURIER - Courier normal. - -
  • FL_COURIER_BOLD - Courier bold. - -
  • FL_COURIER_ITALIC - Courier italic. - -
  • FL_COURIER_BOLD_ITALIC - Courier bold-italic. - -
  • FL_TIMES - Times roman. - -
  • FL_TIMES_BOLD - Times bold. - -
  • FL_TIMES_ITALIC - Times italic. - -
  • FL_TIMES_BOLD_ITALIC - Times bold-italic. - -
  • FL_SYMBOL - Standard symbol font. - -
  • FL_SCREEN - Default monospaced screen font. - -
  • FL_SCREEN_BOLD - Default monospaced bold screen font. - -
  • FL_ZAPF_DINGBATS - Zapf-dingbats font. - - - + The following constants define the standard FLTK fonts: +
  • FL_HELVETICA - Helvetica (or Arial) normal.
    • +
  • FL_HELVETICA_BOLD - Helvetica (or Arial) bold.
    • +
  • FL_HELVETICA_ITALIC - Helvetica (or Arial) oblique.
    • +
  • FL_HELVETICA_BOLD_ITALIC - Helvetica (or Arial) +bold-oblique.
    • +
  • FL_COURIER - Courier normal.
    • +
  • FL_COURIER_BOLD - Courier bold.
    • +
  • FL_COURIER_ITALIC - Courier italic.
    • +
  • FL_COURIER_BOLD_ITALIC - Courier bold-italic.
    • +
  • FL_TIMES - Times roman.
    • +
  • FL_TIMES_BOLD - Times bold.
    • +
  • FL_TIMES_ITALIC - Times italic.
    • +
  • FL_TIMES_BOLD_ITALIC - Times bold-italic.
    • +
  • FL_SYMBOL - Standard symbol font.
    • +
  • FL_SCREEN - Default monospaced screen font.
    • +
  • FL_SCREEN_BOLD - Default monospaced bold screen font.
    • +
  • FL_ZAPF_DINGBATS - Zapf-dingbats font.

    Colors

    - -The following color constants can be used to access the colors in the FLTK -standard color palette: - -
      - -
    • FL_BLACK - -
    • FL_RED - -
    • FL_GREEN - -
    • FL_YELLOW - -
    • FL_BLUE - -
    • FL_MAGENTA - -
    • FL_CYAN - -
    • FL_WHITE - -
    • FL_GRAY0 - -
    • FL_DARK3 - -
    • FL_DARK2 - -
    • FL_DARK1 - -
    • FL_GRAY - -
    • FL_LIGHT1 - -
    • FL_LIGHT2 - -
    • FL_LIGHT3 - -
    - + The following color constants can be used to access the colors in the +FLTK standard color palette: +
      +
    • FL_BLACK
      • +
    • FL_RED
      • +
    • FL_GREEN
      • +
    • FL_YELLOW
      • +
    • FL_BLUE
      • +
    • FL_MAGENTA
      • +
    • FL_CYAN
      • +
    • FL_WHITE
      • +
    • FL_GRAY0
      • +
    • FL_DARK3
      • +
    • FL_DARK2
      • +
    • FL_DARK1
      • +
    • FL_GRAY
      • +
    • FL_LIGHT1
      • +
    • FL_LIGHT2
      • +
    • FL_LIGHT3
      • +

    Cursors

    - -The following constants define the mouse cursors that are available in -FLTK: - -
      -
    • FL_CURSOR_DEFAULT - the default cursor, usually an arrow -
    • FL_CURSOR_ARROW - an arrow pointer -
    • FL_CURSOR_CROSS - crosshair -
    • FL_CURSOR_WAIT - watch or hourglass -
    • FL_CURSOR_INSERT - I-beam -
    • FL_CURSOR_HAND - hand (uparrow on MSWindows) -
    • FL_CURSOR_HELP - question mark -
    • FL_CURSOR_MOVE - 4-pointed arrow -
    • FL_CURSOR_NS - up/down arrow -
    • FL_CURSOR_WE - left/right arrow -
    • FL_CURSOR_NWSE - diagonal arrow -
    • FL_CURSOR_NESW - diagonal arrow -
    • FL_CURSOR_NONE - invisible -
    - -

    FD "When" Conditions

    - -
      - -
    • FL_READ - Call the callback when there is data to be - read. - -
    • FL_WRITE - Call the callback when data can be written - without blocking. - -
    • FL_EXCEPT - Call the callback if an exception occurs on - the file. - -
    - + The following constants define the mouse cursors that are available in +FLTK: +
      +
    • FL_CURSOR_DEFAULT - the default cursor, usually an arrow
      • +
    • FL_CURSOR_ARROW - an arrow pointer
      • +
    • FL_CURSOR_CROSS - crosshair
      • +
    • FL_CURSOR_WAIT - watch or hourglass
      • +
    • FL_CURSOR_INSERT - I-beam
      • +
    • FL_CURSOR_HAND - hand (uparrow on MSWindows)
      • +
    • FL_CURSOR_HELP - question mark
      • +
    • FL_CURSOR_MOVE - 4-pointed arrow
      • +
    • FL_CURSOR_NS - up/down arrow
      • +
    • FL_CURSOR_WE - left/right arrow
      • +
    • FL_CURSOR_NWSE - diagonal arrow
      • +
    • FL_CURSOR_NESW - diagonal arrow
      • +
    • FL_CURSOR_NONE - invisible
      • +
    +

    FD "When" Conditions

    +
      +
    • FL_READ - Call the callback when there is data to be + read.
      • +
    • FL_WRITE - Call the callback when data can be written + without blocking.
      • +
    • FL_EXCEPT - Call the callback if an exception occurs on + the file.
      • +

    Damage Masks

    - -The following damage mask bits are used by the standard FLTK widgets: - -
      - -
    • FL_DAMAGE_CHILD - A child needs to be redrawn. - -
    • FL_DAMAGE_EXPOSE - The window was exposed. - -
    • FL_DAMAGE_SCROLL - The Fl_Scroll widget was - scrolled. - -
    • FL_DAMAGE_OVERLAY - The overlay planes need to be redrawn. - -
    • FL_DAMAGE_ALL - Everything needs to be redrawn. - -
    - - - + The following damage mask bits are used by the standard FLTK widgets: +
      +
    • FL_DAMAGE_CHILD - A child needs to be redrawn.
      • +
    • FL_DAMAGE_EXPOSE - The window was exposed.
      • +
    • FL_DAMAGE_SCROLL - The Fl_Scroll widget was + scrolled.
      • +
    • FL_DAMAGE_OVERLAY - The overlay planes need to be redrawn.
      • +
    • FL_DAMAGE_ALL - Everything needs to be redrawn.
      • +
    +
    • + \ No newline at end of file diff --git a/documentation/events.html b/documentation/events.html index c9471ae25..3b62864b5 100644 --- a/documentation/events.html +++ b/documentation/events.html @@ -1,139 +1,96 @@ - - - -

    6 - Handling Events

    - -This chapter discusses the FLTK event model and how to handle events in your program or -widget. - + +

    6 - Handling Events

    + This chapter discusses the FLTK event model and how to handle events +in your program or widget.

    The FLTK Event Model

    - -Events are identified by the integer argument passed to the Fl_Widget::handle() virtual method. Other -information about the most recent event is stored in static locations -and acquired by calling the Fl::event_*() 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 handle() method). - + Events are identified by the integer argument passed to the +Fl_Widget::handle() virtual method. Other information +about the most recent event is stored in static locations and acquired +by calling the Fl::event_*() 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 handle() + method).

    Mouse Events

    - -

    FL_PUSH

    - -A mouse button has gone down with the mouse pointing at this widget. -You can find out what button by calling Fl::event_button(). You find out the -mouse position by calling Fl::event_x() -and Fl::event_y(). - -

    A widget indicates that it "wants" the mouse click by returning -non-zero from its handle() method. It -will then become the Fl::pushed() widget -and will get FL_DRAG and the matching FL_RELEASE -events. If handle() returns zero then FLTK will try sending -the FL_PUSH to another widget. - -

    FL_DRAG

    - -The mouse has moved with a button held down. - -

    FL_RELEASE

    - -A mouse button has been released. You can find out what button by -calling Fl::event_button(). - -

    FL_MOVE

    - -The mouse has moved without any mouse buttons held down. This event -is sent to the belowmouse() widget. - +

    FL_PUSH

    + A mouse button has gone down with the mouse pointing at this widget. +You can find out what button by calling +Fl::event_button(). You find out the mouse position by +calling Fl::event_x() and +Fl::event_y(). +

    A widget indicates that it "wants" the mouse click by returning +non-zero from its handle() + method. It will then become the +Fl::pushed() widget and will get FL_DRAG and the +matching FL_RELEASE events. If handle() returns zero +then FLTK will try sending the FL_PUSH to another widget.

    +

    FL_DRAG

    + The mouse has moved with a button held down. +

    FL_RELEASE

    + A mouse button has been released. You can find out what button by +calling Fl::event_button(). +

    FL_MOVE

    + The mouse has moved without any mouse buttons held down. This event +is sent to the belowmouse() widget.

    Focus Events

    - -

    FL_ENTER

    - -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 handle() method. It then becomes the Fl::belowmouse() widget and will -receive FL_MOVE and FL_LEAVE events. - -

    FL_LEAVE

    - -The mouse has moved out of the widget. - -

    FL_FOCUS

    - -This indicates an attempt to give a widget the keyboard -focus. - -

    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 handle() method. It then becomes the Fl::focus() widget and gets FL_KEYBOARD -and FL_UNFOCUS events. - -

    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 Fl::event_key() 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. - -

    FL_UNFOCUS

    - -Sent to the previous Fl::focus() when -another widget gets the focus. - +

    FL_ENTER

    + 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 +handle() method. It then becomes the +Fl::belowmouse() widget and will receive FL_MOVE + and FL_LEAVE events. +

    FL_LEAVE

    + The mouse has moved out of the widget. +

    FL_FOCUS

    + This indicates an attempt to give a widget the keyboard focus. +

    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 +handle() method. It then becomes the +Fl::focus() widget and gets FL_KEYBOARD and +FL_UNFOCUS events.

    +

    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 +Fl::event_key() 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.

    +

    FL_UNFOCUS

    + Sent to the previous Fl::focus() + when another widget gets the focus.

    Keyboard Events

    - -

    FL_KEYBOARD

    - -A key press. The key pressed can be found in Fl::event_key(). The text that the key -should insert can be found with Fl::event_text() and its length is in -Fl::event_length(). If you use -the key handle() should return 1. If you return zero then -FLTK assummes you ignored the key. It will then attempt to send it to -a parent widget. If none of them want it, it will change the event into -a FL_SHORTCUT event. - -

    FL_SHORTCUT

    - -If the Fl::focus() is zero or ignores an -FL_KEYBOARD event then FLTK tries sending this event to every -widget it can, until one of them returns non-zero. -FL_SHORTCUT is first sent to the belowmouse() widget, -then 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! - -

    You can also make "global" shortcuts by using Fl::add_handler(). A global shortcut -will work no matter what windows are displayed or which one has the -focus. - +

    FL_KEYBOARD

    + A key press. The key pressed can be found in +Fl::event_key(). The text that the key should insert can +be found with Fl::event_text() + and its length is in +Fl::event_length(). If you use the key handle() + should return 1. If you return zero then FLTK assummes you ignored +the key. It will then attempt to send it to a parent widget. If none +of them want it, it will change the event into a FL_SHORTCUT + event. +

    FL_SHORTCUT

    + If the Fl::focus() is zero +or ignores an FL_KEYBOARD event then FLTK tries sending this +event to every widget it can, until one of them returns non-zero. +FL_SHORTCUT is first sent to the belowmouse() widget, +then 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! +

    You can also make "global" shortcuts by using +Fl::add_handler(). A global shortcut will work no matter +what windows are displayed or which one has the focus.

    Widget Events

    - -

    FL_DEACTIVATE

    - -This widget is no longer active, due to deactivate() being called on -it or one of its parents. active() may still be true after this, the -widget is only active if active() is true on it and all its parents -(use active_r() to check this). - -

    FL_ACTIVATE

    - -This widget is now active, due to activate() being called on it -or one of its parents. - -

    FL_HIDE

    - -This widget is no longer visible, due to show() being called on it or one of -its parents, or due to a parent window being restored. Child -Fl_Windows respond to this by actually creating the window if not -done already, so if you subclass a window, be sure to pass FL_SHOW to -the base class handle() method! - +href="> +show() being called on it or one of its parents, or due to +a parent window being restored. Child Fl_Windows respond to +this by actually creating the window if not done already, so if you +subclass a window, be sure to pass FL_SHOW to the base class +handle() method!

    Clipboard Events

    - -

    FL_PASTE

    - -You should get this event some time after you call Fl::paste(). The contents of Fl::event_text() is the text to insert -and the number of characters is in Fl::event_length(). - -

    FL_SELECTIONCLEAR

    - -The Fl::selection_owner() will get this -event before the selection is moved to another widget. This indicates -that some other widget or program has claimed the selection. - -

    Fl::event_*() methods

    - -FLTK keeps the information about the most recent event in static -storage. This information is good until the next event is processed. -Thus it is valid inside handle() and callback() methods. - -

    These are all trivial inline functions and thus very fast and -small: - -

    - -

    Event Propagation

    - -FLTK follows very simple and unchangeable rules for sending events. The -major innovation is that widgets can indicate (by returning 0 from the -handle() method) that they are not interested in an event, and -FLTK can then send that event elsewhere. This eliminates the need for -"interests" (event masks or tables), and this is probably the main -reason FLTK is much smaller than other toolkits. - -

    Most events are sent directly to the handle() method of the -Fl_Window that the window system says they belong to. The -window (actually the Fl_Group that Fl_Window is a -subclass of) is responsible for sending the events on to any child -widgets. To make the Fl_Group code somewhat easier, FLTK -sends some events (FL_DRAG, FL_RELEASE, -FL_KEYBOARD, FL_SHORTCUT, FL_UNFOCUS, and -FL_LEAVE) directly to leaf widgets. These procedures control -those leaf widgets: - -

    - - - +

    FL_PASTE

    + You should get this event some time after you call +Fl::paste(). The contents of +Fl::event_text() is the text to insert and the number of +characters is in +Fl::event_length(). +

    FL_SELECTIONCLEAR

    + The Fl::selection_owner() + will get this event before the selection is moved to another widget. + This indicates that some other widget or program has claimed the +selection. +

    Fl::event_*() methods

    + FLTK keeps the information about the most recent event in static +storage. This information is good until the next event is processed. +Thus it is valid inside handle() and callback() + methods. +

    These are all trivial inline functions and thus very fast and small:

    + +

    Event Propagation

    + FLTK follows very simple and unchangeable rules for sending events. +The major innovation is that widgets can indicate (by returning 0 from +the handle() method) that they are not interested in an event, +and FLTK can then send that event elsewhere. This eliminates the need +for "interests" (event masks or tables), and this is probably the main +reason FLTK is much smaller than other toolkits. +

    Most events are sent directly to the handle() method of the +Fl_Window that the window system says they belong to. The window +(actually the Fl_Group that Fl_Window is a subclass +of) is responsible for sending the events on to any child widgets. To +make the Fl_Group code somewhat easier, FLTK sends some events +(FL_DRAG, FL_RELEASE, FL_KEYBOARD, +FL_SHORTCUT, FL_UNFOCUS, and FL_LEAVE) directly +to leaf widgets. These procedures control those leaf widgets:

    + + \ No newline at end of file diff --git a/documentation/fluid.html b/documentation/fluid.html index c54a8c3e0..fc6519cbd 100644 --- a/documentation/fluid.html +++ b/documentation/fluid.html @@ -1,151 +1,104 @@ - - - -

    8 - Programming with FLUID

    - -This chapter shows how to use the Fast Light User-Interface Designer ("FLUID") to create -your GUIs. - + +

    8 - Programming with FLUID

    + This chapter shows how to use the Fast Light User-Interface Designer +("FLUID") to create your GUIs.

    What is FLUID?

    - -The Fast Light User Interface Designer, or "FLUID", is a graphical -editor that is used to produce FLTK source code. - -

    FLUID edits and saves its state in ".fl" files. These files are -text, and you can (with care) edit them in a text editor, perhaps to -get some special effects. - -

    FLUID can "compile" the .fl file into a .cxx and a .h file. The .cxx -file defines all the objects from the .fl file and the .h file -declares all the global ones. - -

    A simple program can be made by putting all your code (including a -main() function) into the .fl file and thus making the .cxx -file a single source file to compile. Most programs are more complex -than this, so you write other .cxx files that call the FLUID -functions. These .cxx files must #include the .h file or -they can #include the .cxx file so it still appears to be a single -source file. - -

    - -

    Normally the FLUID file defines one or more "functions", which -output C++ functions. Each function defines a one or more FLTK -windows, and all the widgets that go inside those windows. - -

    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 to -them is stored. - -

    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 .cxx file. - -

    A Short Tutorial

    - -
      - -
    1. Type "FLUID&" - -
    2. Pick "New/code/function" off the menu. - -
    3. Hit Tab, Delete to delete the function name and hit OK. This is - how you get FLUID to output a "main()" function. The text "main()" - with a triangle next to it should appear highlighted in the main - window. - -
    4. Pick "New/group/Window" off the menu. - -
    5. Move the new window and resize it to the size you want. - -
    6. Pick "New/buttons/Button" off the menu. - -
    7. Hit the "OK" button to dismiss the panel that appears. - -
    8. In the window you created, try moving the button by dragging it - around. Notice that it "snaps" to fixed locations. If you want to - drag it smoothly, hold down Alt. You can also change the size of the - steps with Edit/Preferences. - -
    9. Try resizing the widget by dragging the edges and corners. - -
    10. Type Alt+c to copy the widget. - -
    11. Type Alt+v to paste a copy into the window. - -
    12. Type Alt+v several times. - -
    13. Drag the widgets and resize them so they don't overlap. Notice - that you have to click a widget to pick it first, then drag it. - -
    14. Try selecting several widgets by dragging a box around them. Check - what happens when you move them, or when you drag an edge to resize - them. - -
    15. You can also use Shift+click to toggle widgets on and off. - -
    16. You can also select widgets by clicking on them in the list in the - main window, try that. - -
    17. Double-click one of the widgets. You will get a control panel. - -
    18. Try changing the "label". Try changing other items near the top of - the panel. To see any changes to the box type clearer, type "Alt+o" - to make the red overlay disappear. - -
    19. Type "#include <stdlib.h>" into the first line of "extra code:". - -
    20. Type "exit(0);" into the "callback:". - -
    21. Hit OK. - -
    22. Pick "File/Save As" off the menu. - -
    23. Type "test.fl" into the file chooser and hit return. - -
    24. Pick "File/Write Code" off the menu, hit OK on the confirmation panel. - -
    25. Go back to your terminal window. Type "more test.cxx" and "more - test.h" and you can see the code it made. Also try "more test.fl" to - see how FLUID saves its data. - -
    26. Type "make test" (you may have to add libaries to your Makefile). - -
    27. Type "./test" to run your program. - -
    28. Try the buttons. The one you put the code into will exit the - program. - -
    29. Type "Alt+Q" to exit FLUID. - -
    30. Ok, now try to make a real program. - -
    - -

    Running FLUID Under UNIX

    - -To run FLUID under UNIX, type: - - - -to edit the .fl file filename.fl. If the file does not exist -you will get an error pop-up, but if you dismiss it you will be editing -a blank 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). - -

    You can provide any of the standard FLTK switches before the name: - -

    +

    The Widget Browser

    + + +
    The main window shows a menu bar and a scrolling browser of all +the defined widgets. The name of the .fl file being edited is shown in +the window title. +

    The widgets are stored in a hierarchy. You can open and close a +level by clicking the "triangle" at the left of a widget. This widget +is the parent, and all the widgets listed below it are its +children. There can be zero children.

    +

    The top level of the hierarchy is functions. Each of these +will produce a single C++ public function in the output .cxx file. +Calling the function will create all of its child windows.

    +

    The second level of the hierarchy is windows. Each of these +produces an instance of class Fl_Window.

    +

    Below that are either widgets (subclasses of Fl_Widget) or +groups of widgets (including other groups). Plain groups are for +layout, navigation, and resize purposes. Tab groups provide the +well-known file-card tab interface.

    +

    Widgets are shown in the browser as either their name (such +as "main_panel" in the example), or if unnamed as their type + and label (such as "Button "the green"").

    +
    + You select widgets by clicking on their names, which highlights +them (you can also select widgets from any displayed window). You can +select many widgets by dragging the mouse across them, or by using +shift+click to toggle them on and off. To select no widgets, click in +the blank area under the last widget. Notice that hidden children may +be selected and there is no visual indication of this. +

    You open widgets by double clicking them, or (to open several +widgets you have picked) by typing the F1 key. This will bring up a +control panel or window from which you can change the widget.

    +

    Menu Items

    +

    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:

    +

    File/Open... (Alt+Shift+O)

    + Discard the current editing session and read in a different .fl file. +You are asked for confirmation if you have changed the current data. +

    FLUID can also read .fd files produced by the Forms and XForms +"fdesign" programs. It is best to read them with Merge. FLUID does +not understand everything in a .fd file, and will print a warning +message on the controlling terminal for all data it does not +understand. You will probably need to edit the resulting setup to fix +these errors. Be careful not to save the file without changing the +name, as FLUID will write over the .fd file with its own format, which +fdesign cannot read!

    File/Save (Alt+s)

    - -Write the current data to the .fl file. If the file is unnamed -(because FLUID was started with no name) then ask for a file name. - + Write the current data to the .fl file. If the file is unnamed +(because FLUID was started with no name) then ask for a file name.

    File/Save As...(Alt+Shift+S)

    - -Ask for a new name to save the file as, and save it. - + Ask for a new name to save the file as, and save it.

    File/Merge... (Alt+i)

    - -Insert the contents of another .fl file, without changing the name of -the current .fl file. All the functions (even if they have the same -names as the current ones) are added, you will have to use cut/paste -to put the widgets where you want. - + Insert the contents of another .fl file, without changing the name of +the current .fl file. All the functions (even if they have the same +names as the current ones) are added, you will have to use cut/paste to +put the widgets where you want.

    File/Write code (Alt+Shift+C)

    - -"Compiles" the data into a .cxx and .h file. These are exactly the same -as the files you get when you run FLUID with the -c switch. - -

    The output file names are the same as the .fl file, with the -leading directory and trailing ".fl" stripped, and ".h" or ".cxx" -appended. Currently there is no way to override this. - + "Compiles" the data into a .cxx and .h file. These are exactly the +same as the files you get when you run FLUID with the -c switch. +

    The output file names are the same as the .fl file, with the leading +directory and trailing ".fl" stripped, and ".h" or ".cxx" appended. + Currently there is no way to override this.

    File/Quit (Alt+q)

    - -Exit FLUID. You are asked for confirmation if you have changed the -current data. - + Exit FLUID. You are asked for confirmation if you have changed the +current data.

    Edit/Undo (Alt+z)

    - -Don't you wish... This isn't implemented yet. You should do save -often so that any mistakes you make don't irretrivably destroy your -data. - + Don't you wish... This isn't implemented yet. You should do save +often so that any mistakes you make don't irretrivably destroy your +data.

    Edit/Cut (Alt+x)

    - -Delete the selected widgets and all their children. These are saved -to a "clipboard" file (/usr/tmp/cut_buffer.fl) and can be pasted back -into this FLUID or any other one. - + Delete the selected widgets and all their children. These are saved +to a "clipboard" file (/usr/tmp/cut_buffer.fl) and can be pasted back +into this FLUID or any other one.

    Edit/Copy (Alt+c)

    - -Copy the selected widgets and all their children to the "clipboard" file. - + Copy the selected widgets and all their children to the "clipboard" +file.

    Edit/Paste (Alt+c)

    - -Paste in the widgets in the clipboard file. - -

    If the widget is a window, it is added to whatever function is -selected, or contains the current selection. - -

    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. - -

    To avoid confusion, it is best to select exactly one widget before -doing a paste. - -

    Cut/paste is the only way to change the parent of a widget. - + Paste in the widgets in the clipboard file. +

    If the widget is a window, it is added to whatever function is +selected, or contains the current selection.

    +

    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.

    +

    To avoid confusion, it is best to select exactly one widget before +doing a paste.

    +

    Cut/paste is the only way to change the parent of a widget.

    Edit/Select All (Alt+a)

    - -Select all widgets in the same group as the current selection. - -

    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. - + Select all widgets in the same group as the current selection. +

    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.

    Edit/Open... (F1 or double click)

    - -If the current widget is a window and it is not displayed, display it. -Otherwise open a control panel for the most recent (and possibly all) -selected widgets. - + If the current widget is a window and it is not displayed, display it. +Otherwise open a control panel for the most recent (and possibly all) +selected widgets.

    Edit/Sort

    - -All the selected widgets are sorted into left to right, top to bottom -order. You need to do this to make navigation keys in FLTK work -correctly. You may then fine-tune the sorting with "Earlier" and -"Later". This does not affect the positions of windows or functions. - + All the selected widgets are sorted into left to right, top to bottom +order. You need to do this to make navigation keys in FLTK work +correctly. You may then fine-tune the sorting with "Earlier" and +"Later". This does not affect the positions of windows or functions.

    Edit/Earlier (F2)

    - -All the selected widgets are moved one earlier in order amoung the -children of their parent (if possible). This will affect navigation -order, and if the widgets overlap it will affect how they draw, as the -later widget is drawn on top of the earlier one. You can also use -this to reorder functions and windows within functions. - + All the selected widgets are moved one earlier in order amoung the +children of their parent (if possible). This will affect navigation +order, and if the widgets overlap it will affect how they draw, as the +later widget is drawn on top of the earlier one. You can also use this +to reorder functions and windows within functions.

    Edit/Later (F3)

    - -All the selected widgets are moved one later in order amoung the -children of their parent (if possible). - + All the selected widgets are moved one later in order amoung the +children of their parent (if possible).

    Edit/Group (F7)

    - -Create a new Fl_Group and make all the currently selected widgets be -children of it. - + Create a new Fl_Group and make all the currently selected widgets be +children of it.

    Edit/Ungroup (F8)

    - -If all the children of a group are selected, delete that group and -make them all be children of its parent. - + If all the children of a group are selected, delete that group and +make them all be children of its parent.

    Edit/Overlays on/off (Alt+o)

    - -Toggle the display of the red overlays off, without changing the -selection. This makes it easier to see box borders and how the layout -looks. The overlays will be forced back on if you change the selection. - + Toggle the display of the red overlays off, without changing the +selection. This makes it easier to see box borders and how the layout +looks. The overlays will be forced back on if you change the +selection.

    Edit/Preferences (Alt+p)

    - -Currently the only preferences are for the "alignment grid" that all -widgets snap to when you move them and resize them, and for the "snap" -which is how far a widget has to be dragged from its original -position to actually change. - + Currently the only preferences are for the "alignment grid" that all +widgets snap to when you move them and resize them, and for the "snap" +which is how far a widget has to be dragged from its original position +to actually change.

    New/code/Function

    - -Create a new C function. You will be asked for a name for the -function. This name should be a legal C++ function template, without -the return type. You can pass arguments, they can be referred to by -code you type into the individual widgets. - -

    If the function contains any unnamed windows, it will be declared -as returning an Fl_Window*. The unnamed window will be returned from -it (more than one unnamed window is useless). If the function -contains only named windows it will be declared as returning void. - -

    It is possible to make the .cxx output be a self-contained program -that can be compiled and executed. This is done by deleting the -function name, in which case "main(argc,argv)" is used. The function -will call show() on all the windows it creates and then call -Fl::run(). This can be used to test resize behavior or other parts of -the user interface. I'm not sure if it is possible to create really -useful programs using just FLUID. - -

    You can change the function name by double clicking the function. - + Create a new C function. You will be asked for a name for the +function. This name should be a legal C++ function template, without +the return type. You can pass arguments, they can be referred to by +code you type into the individual widgets. +

    If the function contains any unnamed windows, it will be declared as +returning an Fl_Window*. The unnamed window will be returned from it +(more than one unnamed window is useless). If the function contains +only named windows it will be declared as returning void.

    +

    It is possible to make the .cxx output be a self-contained program +that can be compiled and executed. This is done by deleting the +function name, in which case "main(argc,argv)" is used. The function +will call show() on all the windows it creates and then call Fl::run(). + This can be used to test resize behavior or other parts of the user +interface. I'm not sure if it is possible to create really useful +programs using just FLUID.

    +

    You can change the function name by double clicking the function.

    New/Window

    - -Create a new Fl_Window. It is added to the currently selected -function, or to the function containing the currently selected item. -The window will appear, sized to 100x100. You will want to resize it -to whatever size you require. - -

    You also get the window's control panel, which is almost exactly -the same as any other Fl_Widget, and is described in the next chapter. - + Create a new Fl_Window. It is added to the currently selected +function, or to the function containing the currently selected item. +The window will appear, sized to 100x100. You will want to resize it +to whatever size you require. +

    You also get the window's control panel, which is almost exactly the +same as any other Fl_Widget, and is described in the next chapter.

    New/...

    - -All other items on the New menu are subclasses of Fl_Widget. Creating -them will add them to the currently selected group or window, or the -group or window containing the currently selected widget. The initial -dimensions and position are chosen by copying the current widget, if -possible. - -

    When you create the widget you will get the widget's control panel, -described in the next chapter. - + All other items on the New menu are subclasses of Fl_Widget. Creating +them will add them to the currently selected group or window, or the +group or window containing the currently selected widget. The initial +dimensions and position are chosen by copying the current widget, if +possible. +

    When you create the widget you will get the widget's control panel, +described in the next chapter.

    Help/About FLUID

    - -Pops up a panel showing the version of FLUID. - + Pops up a panel showing the version of FLUID.

    Help/Manual

    - -Not yet implemented. Use a HTML or PDF file viewer to read these pages -instead. - -

    The Widget Panel

    - - - - - - -
    - -When you double-click a widget or a set of widgets you will get the -"widget attribute panel". - -

    When you change attributes using this panel, the changes are -reflected immediately in the window. It is useful to hit the "no -overlay" button (or type Alt+o) to hide the red overlay so you can see -the widgets more accurately, especially when setting the box type. - -

    If you have several widgets selected, they may have different -values for the fields. In this case the value for one of the -widgets is shown. But if you change this value, all the -selected widgets are changed to the new value. - -

    Hitting "OK" makes the changes permanent. Selecting a different -widget also makes the changes permanent. FLUID checks for simple -syntax errors in any code (such as mismatched parenthesis) before -saving any text. - -

    - -"Revert" or "Cancel" put everything back to when you last brought -up the panel or hit OK. However in the current version of FLUID, -changes to "visible" attributes (such as the color, label, box) are -not undone by revert or cancel. Changes to code like the callbacks -is undone, however. - - -

    Widget Attributes

    - + Not yet implemented. Use a HTML or PDF file viewer to read these +pages instead. +

    The Widget Panel

    + + +
    When you double-click a widget or a set of widgets you will get +the "widget attribute panel". +

    When you change attributes using this panel, the changes are +reflected immediately in the window. It is useful to hit the "no +overlay" button (or type Alt+o) to hide the red overlay so you can see +the widgets more accurately, especially when setting the box type.

    +

    If you have several widgets selected, they may have different values +for the fields. In this case the value for one of the widgets +is shown. But if you change this value, all the selected +widgets are changed to the new value.

    +

    Hitting "OK" makes the changes permanent. Selecting a different +widget also makes the changes permanent. FLUID checks for simple +syntax errors in any code (such as mismatched parenthesis) before +saving any text.

    +
    + "Revert" or "Cancel" put everything back to when you last brought up +the panel or hit OK. However in the current version of FLUID, changes +to "visible" attributes (such as the color, label, box) are not undone +by revert or cancel. Changes to code like the callbacks is undone, +however.     +

    Widget Attributes

    Name (text field)

    - -Name of a global C variable to declare, and to store a pointer to this -widget into. This variable will be of type "<class>*". If the name -is blank then no variable is created. - -

    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. - + Name of a global C variable to declare, and to store a pointer to this +widget into. This variable will be of type "<class>*". If the name is +blank then no variable is created. +

    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.

    Type (upper-right pulldown menu)

    - -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.

    Box (pulldown menu)

    - -The boxtype to draw as a background for the widget. - -

    Many widgets will work, and draw faster, with a "frame" instead of -a "box". A frame does not draw the colored interior, leaving whatever -was already there visible. Be careful, as FLUID may draw this ok but -the real program leave unwanted stuff inside the widget. - -

    If a window is filled with child widgets, you can speed up -redrawing by changing the window's box type to "NO_BOX". FLUID will -display a checkerboard for any areas that are not colored in by boxes -(notice that this checkerboard is not drawn by the resulting program, -instead random garbage is left there). - + The boxtype to draw as a background for the widget. +

    Many widgets will work, and draw faster, with a "frame" instead of a +"box". A frame does not draw the colored interior, leaving whatever +was already there visible. Be careful, as FLUID may draw this ok but +the real program leave unwanted stuff inside the widget.

    +

    If a window is filled with child widgets, you can speed up redrawing +by changing the window's box type to "NO_BOX". FLUID will display a +checkerboard for any areas that are not colored in by boxes (notice +that this checkerboard is not drawn by the resulting program, instead +random garbage is left there).

    Color

    - -

    The color to draw the box with. - +

    The color to draw the box with.

    Color2

    - -

    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. - +

    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.

    Label

    - -String to print next to or inside the button. - -

    You can put newlines into the string to make multiple lines, the -easiest way is by typing ctrl+j. - + String to print next to or inside the button. +

    You can put newlines into the string to make multiple lines, the +easiest way is by typing ctrl+j.

    Label style (pull down menu)

    - -How to draw the label. Normal, shadowned, engraved, and embossed -change the appearance of the text. "symbol" requires the label to -start with an '@' sign to draw a named     symbol. - -

    From this menu you can also pick "Image...". This lets you use the contents -of an image file (currently an xpm pixmap or xbm bitmap) to label the -widget. - + How to draw the label. Normal, shadowned, engraved, and embossed +change the appearance of the text. "symbol" requires the label to +start with an '@' sign to draw a named +symbol. +

    From this menu you can also pick +"Image...". This lets you use the contents of an image file +(currently an xpm pixmap or xbm bitmap) to label the widget.

    Label alignement (buttons)

    - -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.

    Label font

    - -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.

    Label size

    - -Point size for the font to draw the label in. Ignored by symbols, -bitmaps, and pixmaps. To see the result without dismissing the panel, -type the new number and then Tab. - + Point size for the font to draw the label in. Ignored by symbols, +bitmaps, and pixmaps. To see the result without dismissing the panel, +type the new number and then Tab.

    Label color

    - -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).

    Text font, size, color

    - -Some widgets display text, such as input fields, pull-down menus, -browsers. You can change this here. - + Some widgets display text, such as input fields, pull-down menus, +browsers. You can change this here.

    Visible

    - -If you turn this off the widget is hidden initially. Don't change -this for windows or for the immediate children of a Tabs group. - + If you turn this off the widget is hidden initially. Don't change +this for windows or for the immediate children of a Tabs group.

    Active

    - -If you turn this off the widget is deactivated initially. Currently -no FLTK widgets display the fact that they are inactive (like by graying -out), but this may change in the future. - + If you turn this off the widget is deactivated initially. Currently +no FLTK widgets display the fact that they are inactive (like by +graying out), but this may change in the future.

    Resizable

    - -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. - -

    Only one child can be resizable. Turning this on turns it off for -other children. - -

    You can get more complex behavior by making invisible boxes the -resizable widget, or by using hierarchies of groups. Unfortunatley -the only way to test it is to compile the program. Resizing the FLUID -window is not the same as what will happen in the user program. - + 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. +

    Only one child can be resizable. Turning this on turns it off for +other children.

    +

    You can get more complex behavior by making invisible boxes the +resizable widget, or by using hierarchies of groups. Unfortunatley the +only way to test it is to compile the program. Resizing the FLUID +window is not the same as what will happen in the user program.

    Hotspot

    - -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 when the FLUID -function is called, 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 show(). - + 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 when the FLUID +function is called, 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 show().

    subclass

    - -This is how you put your own subclasses of Fl_Widget in. Whatever -identifier you type in here will be the class that is instantiated. - -

    In addition, no #include header file is put in the .h file. You -must provide a #include line as the first of the "extra code" which -declares your subclass. - -

    The class had better be similar to the class you are spoofing. It -does not have to be a subclass. It is sometimes useful to change this -to another FLTK class: currently the only way to get a double-buffered -window is to change this field for the window to "Fl_Double_Window" -and to add "#include <FL/Fl_Double_Window.h>" to the extra code. - + This is how you put your own subclasses of Fl_Widget in. Whatever +identifier you type in here will be the class that is instantiated. +

    In addition, no #include header file is put in the .h file. You +must provide a #include line as the first of the "extrawhich declares +your subclass.

    +

    The class had better be similar to the class you are spoofing. It +does not have to be a subclass. It is sometimes useful to change this +to another FLTK class: currently the only way to get a double-buffered +window is to change this field for the window to "Fl_Double_Window" and +to add "#include <FL/Fl_Double_Window.h>" to the extra code.

    Extra code

    - -These four fields let you type in literal lines of code to dump into -the .h or .cxx files. - -

    If the text starts with a '#' or the word "extern" then FLUID -thinks this is an "include" line, and it is written to the .h file. -If the same include line occurs several times then only one copy is -written. - -

    All other lines are "code" lines. The widget being constructed is -pointed to by the local variable 'o'. The window being constructed is -pointed to by the local variable 'w'. You can also access any -arguments passed to the function here, and any named widgets that are -before this one. - -

    FLUID will check for matching parenthesis, braces, and quotes, but -does not do much other error checking. Be careful here, as it may be -hard to figure out what widget is producing an error in the compiler. -If you need more than 4 lines you probably should call a function in -your own .cxx code. - + These four fields let you type in literal lines of code to dump into +the .h or .cxx files. +

    If the text starts with a '#' or the word "extern" then FLUID thinks +this is an "include" line, and it is written to the .h file. If the +same include line occurs several times then only one copy is written.

    +

    All other lines are "code" lines. The widget being constructed is +pointed to by the local variable 'o'. The window being constructed is +pointed to by the local variable 'w'. You can also access any +arguments passed to the function here, and any named widgets that are +before this one.

    +

    FLUID will check for matching parenthesis, braces, and quotes, but +does not do much other error checking. Be careful here, as it may be +hard to figure out what widget is producing an error in the compiler. +If you need more than 4 lines you probably should call a function in +your own .cxx code.

    Callback

    - -This can either be the name of a function, or a small snippet of -code. FLUID thinks that if there is any punctuation then it is code. - -

    A name names a function in your own code. It must be declared as -"void <name>(<class>*,void*)". - -

    A code snippet is inserted into a static function in the .cxx output -file. The function prototype is -"void f(<class>* o, void* v)", so you can refer to -the widget as 'o' and the user_data as 'v'. FLUID will check for -matching parenthesis, braces, and quotes, but does not do much other -error checking. Be careful here, as it may be hard to figure out what -widget is producing an error in the compiler. - -

    If the callback is blank then no callback is set. - + This can either be the name of a function, or a small snippet of code. + FLUID thinks that if there is any punctuation then it is code. +

    A name names a function in your own code. It must be declared as +"voidname>(<class>*,void*)".

    +

    A code snippet is inserted into a static function in the .cxx output +file. The function prototype is "voidclass>*so you can refer to the +widget as 'o' and the user_data as 'v'. FLUID will check for matching +parenthesis, braces, and quotes, but does not do much other error +checking. Be careful here, as it may be hard to figure out what widget +is producing an error in the compiler.

    +

    If the callback is blank then no callback is set.

    user_data

    - -

    This is a value for the user_data() of the widget. If blank the -default value of zero is used. This can be any piece of C code that -can be put "(void*)(<here>)". - +

    This is a value for the user_data() of the widget. If blank the +default value of zero is used. This can be any piece of C code that +can be put "(void*)(<here>)".

    User data type

    - -The "void*" in the callback function prototypes is replaced with -this. You may want to use "long" for old XForms code. Be warned that -anything other than "void*" is not guaranteed to work by the C++ spec! -However on most architectures other pointer types are ok, and long is -usually ok. - + The "void*" in the callback function prototypes is replaced with this. + You may want to use "long" for old XForms code. Be warned that +anything other than "void*" is not guaranteed to work by the C++ spec! +However on most architectures other pointer types are ok, and long is +usually ok.

    When

    - -When to do the callback. Can be "never", "changed", "release". The -value of "enter key" is only useful for text input fields. The "no -change" button means the callback is done on the matching event even -if the data is not changed. - -

    There are rare but useful other values for the when() field that -are not in the menu. You should use the extra code fields to put -these values in. - - -

    Selecting & Moving Widgets

    - -

    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. - -

    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. - -

    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. - -

    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. - -

    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. - -

    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. - -

    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. - -

    Type Alt+o to temporarily toggle the overlay off without changing -the selection, so you can see the widget borders. - -

    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. - -

    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: - + When to do the callback. Can be "never", "changed", "release". The +value of "enter key" is only useful for text input fields. The "no +change" button means the callback is done on the matching event even if +the data is not changed. +

    There are rare but useful other values for the when() field that are +not in the menu. You should use the extra code fields to put these +values in.

    +

    Selecting Moving Widgets

    +

    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.

    +

    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.

    +

    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.

    +

    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.

    +

    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.

    +

    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.

    +

    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.

    +

    Type Alt+o to temporarily toggle the overlay off without changing +the selection, so you can see the widget borders.

    +

    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.

    +

    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:

    Border

    - -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.

    xclass

    - -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. - -     -

    Image Labels

    - -

    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. - -

    The contents of the image file are written to the .cxx file, -so if you wish to distribute the C code, you only need to copy the .cxx -file, not the images. If many widgets share the same image then only -one copy is written. - -

    However the file name is stored in the .fl file, so to read -the .fl file you need the image files as well. Filenames are relative -to the location the .fl file is (not necessarily the current -directory). I recommend you either put the images in the same -directory as the .fl file, or use absolute path names. - + 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. +

    Image Labels

    +

    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.

    +

    The contents of the image file are written to the .cxx file, +so if you wish to distribute the C code, you only need to copy the .cxx +file, not the images. If many widgets share the same image then only +one copy is written.

    +

    However the file name is stored in the .fl file, so to read +the .fl file you need the image files as well. Filenames are relative +to the location the .fl file is (not necessarily the current +directory). I recommend you either put the images in the same +directory as the .fl file, or use absolute path names.

    Notes for all image types

    - -

    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. - -

    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. - -

    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. - -

    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. - -

    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. - +

    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.

    +

    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.

    +

    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.

    +

    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.

    +

    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.

    XBM (X bitmap files)

    - -

    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". - -

    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. - -

    The program "bitmap" on the X distribution does an ok job of -editing bitmaps. - +

    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".

    +

    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.

    +

    The program "bitmap" on the X distribution does an ok job of editing +bitmaps.

    XPM (X pixmap files)

    - -

    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. - -

    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. - -

    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. - -

    I have not found any good editors for small iconic pictures. For -pixmaps I have used XPaint. This -(and most other) painting programs are designed for large full color -images and are difficult to use to edit an image of small size and few -colors. - +

    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.

    +

    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.

    +

    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.

    +

    I have not found any good editors for small iconic pictures. For +pixmaps I have used +XPaint. This (and most other) painting programs are designed for +large full color images and are difficult to use to edit an image of +small size and few colors.

    GIF files

    - -

    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. - -

    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. - -

    Behavior and performance with large .gif files is not guaranteed! - - - +

    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.

    +

    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.

    +

    Behavior and performance with large .gif files is not guaranteed!

    + \ No newline at end of file diff --git a/documentation/forms.html b/documentation/forms.html index c1c69cf0e..6fd5282d7 100644 --- a/documentation/forms.html +++ b/documentation/forms.html @@ -1,271 +1,200 @@ - - - -

    E - Forms Compatibility

    - -This appendix describes the Forms compatibility included with FLTK. - + +

    E - Forms Compatibility

    + This appendix describes the Forms compatibility included with FLTK.

    Importing Forms Layout Files

    - -FLUID 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. - -

    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, -<FL/forms.H>. - +FLUID 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. +

    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, +<FL/forms.H>.

    Using the Compatibility Header File

    - -You should be able to compile existing Forms or XForms source code -by changing the include directory switch to your compiler so that the -forms.h file supplied with FLTK is included. Take a look at -forms.h to see how it works, but the basic trick is lots of -inline functions. Most of the XForms demo programs work without -changes. - -

    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. - -

    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. - -

    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 forms.H a lot. - -

    Problems you will encounter

    - -

    Many parts of XForms use X-specific structures like XEvent -in their interface. I did not emulate these! Unfortunately these -features (such as the "canvas" widget) are needed by most large -programs. You will need to rewrite these to use FLTK subclasses. - -

    Fl_Free widgets emulate the -old Forms "free" widget. It may be useful for porting programs -that change the handle() function on widgets, but you will -still need to rewrite things. - -

    Fl_Timer widgets are provided to -emulate the XForms timer. These work, but are quite inefficient and -inaccurate compared to using Fl::add_timeout(). - -

    All instance variables are hidden. -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()". - -

    const char * arguments to most FLTK methods are simply -stored, while Forms would strdup() the passed string. This is -most noticable with the label of widgets. Your program must always -pass static data such as a string constant or malloc'd buffer to -label(). If you are using labels to display program output -you may want to try the Fl_Output widget. - -

    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. - -

    fdesign outputs a setting of a "fdui" instance variable to the main -window. I did not emulate this because I wanted all instance variables -to be hidden. You can store the same information in the -user_data() field of a window. To do this, search through -the fdesign output for all occurances of "->fdui" and edit to use -"->user_data()" instead. This will require casts and is not trivial. - -

    The prototype for the functions passed to fl_add_timeout() -and fl_set_idle_callback() callback are different. - -

    All the following XForms calls are missing:

    - -

    - -

    Additional Notes

    - -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: - -

    Does Not Run In Background

    - -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. - -

    You Cannot Use IRISGL windows or fl_queue

    - -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. - -

    None of this works with FLTK. Nor will it compile, the necessary -calls are not in the interface. - -

    You have to make a subclass of Fl_Gl_Window and write a draw() -method and handle() method. This may require anywhere from a trivial -to a major rewrite. - -

    If you draw into the overlay planes you will have to also write a -draw_overlay() method and call redraw_overlay() on the -OpenGL window. - -

    One easy way to hack your program so it works is to make the -draw() and handle() methods on your window set some -static variables, storing what event happened. Then in the main loop -of your program, call Fl::wait() and then check these -variables, acting on them as though they are events read from -fl_queue. - -

    You Must Use OpenGL to Draw Everything

    - -

    The file <FL/gl.h> defines replacements for a lot of -IRISGL calls, translating them to OpenGL. There are much better -translators available that you might want to investigate. - -

    You Cannot Make Forms Subclasses

    - -Programs that call fl_make_object or directly setting the -handle routine will not compile. You have to rewrite them to use a -subclass of Fl_Widget. It is important to note that the -handle() method is not exactly the same as the -handle() function of Forms. Where a Forms handle() -returned non-zero, your handle() must call -do_callback(). And your handle() must return non-zero -if it "understood" the event. - -

    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. - -

    If your subclass draws into the overlay you are in trouble and will -have to rewrite things a lot. - -

    You Cannot Use <device.h>

    - -If you have written your own "free" widgets you will probably get a -lot of errors about "getvaluator". You should substitute: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FormsFLTK
    MOUSE_XFl::event_x_root()
    MOUSE_YFl::event_y_root()
    LEFTSHIFTKEY,RIGHTSHIFTKEYFl::event_shift()
    CAPSLOCKKEYFl::event_capslock()
    LEFTCTRLKEY,RIGHTCTRLKEYFl::event_ctrl()
    LEFTALTKEY,RIGHTALTKEYFl::event_alt()
    MOUSE1,RIGHTMOUSEFl::event_state()&FL_BUTTON3
    MOUSE2,MIDDLEMOUSEFl::event_state()&FL_BUTTON2
    MOUSE3,LEFTMOUSEFl::event_state()&FL_BUTTON1
    - -Anything else in getvaluator and you are on your own... - -

    Font Numbers Are Different

    - -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: - -
      -fl_font_name(3,"*courier-medium-r-no*");
-fl_font_name(4,"*courier-bold-r-no*");
-fl_font_name(5,"*courier-medium-o-no*");
-fl_font_name(6,"*times-medium-r-no*");
-fl_font_name(7,"*times-bold-r-no*");
-fl_font_name(8,"*times-medium-i-no*");
-fl_font_name(9,"*bookman-light-r-no*");
-fl_font_name(10,"*bookman-demi-r-no*");
-fl_font_name(11,"*bookman-light-i-no*");
-
    - - - + You should be able to compile existing Forms or XForms source code by +changing the include directory switch to your compiler so that the +forms.h file supplied with FLTK is included. Take a look at +forms.h to see how it works, but the basic trick is lots of inline +functions. Most of the XForms demo programs work without changes. +

    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.

    +

    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.

    +

    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 forms.H a lot.

    +

    Problems you will encounter

    +

    Many parts of XForms use X-specific structures like XEvent + in their interface. I did not emulate these! Unfortunately these +features (such as the "canvas" widget) are needed by most large +programs. You will need to rewrite these to use FLTK subclasses.

    +

    Fl_Free widgets emulate +the old Forms "free" widget. It may be useful for porting +programs that change the handle() function on widgets, but you +will still need to rewrite things.

    +

    Fl_Timer widgets are +provided to emulate the XForms timer. These work, but are quite +inefficient and inaccurate compared to using +Fl::add_timeout().

    +

    All instance variables are hidden. 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()".

    +

    const char * arguments to most FLTK methods are simply +stored, while Forms would strdup() the passed string. This is +most noticable with the label of widgets. Your program must always +pass static data such as a string constant or malloc'd buffer to +label(). If you are using labels to display program output you +may want to try the Fl_Output + widget.

    +

    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.

    +

    fdesign outputs a setting of a "fdui" instance variable to the main +window. I did not emulate this because I wanted all instance variables +to be hidden. You can store the same information in the user_data() + field of a window. To do this, search through the fdesign output for +all occurances of "->fdui" and edit to use "->user_data()" instead. + This will require casts and is not trivial.

    +

    The prototype for the functions passed to fl_add_timeout() + and fl_set_idle_callback() callback are different.

    +

    All the following XForms calls are missing:

    +

    +

      +
    • FL_REVISION, fl_library_version()
      • +
    • FL_RETURN_DBLCLICK (use Fl::event_clicks())
      • +
    • fl_add_signal_callback()
      • +
    • fl_set_form_atactivate() fl_set_form_atdeactivate() +
      • +
    • fl_set_form_property()
      • +
    • fl_set_app_mainform(), fl_get_app_mainform()
      • +
    • fl_set_form_minsize(), fl_set_form_maxsize()
      • +
    • fl_set_form_event_cmask(), fl_get_form_event_cmask() +
      • +
    • fl_set_form_dblbuffer(), fl_set_object_dblbuffer() + (use an Fl_Double_Window instead)
      • +
    • fl_adjust_form_size()
      • +
    • fl_register_raw_callback()
      • +
    • fl_set_object_bw(), fl_set_border_width()
      • +
    • fl_set_object_resize(), fl_set_object_gravity()
      • +
    • fl_set_object_shortcutkey()
      • +
    • fl_set_object_automatic()
      • +
    • fl_get_object_bbox() (maybe FLTK should do this)
      • +
    • fl_set_object_prehandler(), fl_set_object_posthandler() +
      • +
    • fl_enumerate_fonts()
      • +
    • Most drawing functions
      • +
    • fl_set_coordunit() (FLTK uses pixels all the time)
      • +
    • fl_ringbell()
      • +
    • fl_gettime()
      • +
    • fl_win*() (all these functions)
      • +
    • fl_initialize(argc,argv,x,y,z) ignores last 3 arguments
      • +
    • fl_read_bitmapfile(), fl_read_pixmapfile()
      • +
    • fl_addto_browser_chars()
      • +
    • FL_MENU_BUTTON just draws normally
      • +
    • fl_set_bitmapbutton_file(), fl_set_pixmapbutton_file() +
      • +
    • FL_CANVAS objects
      • +
    • FL_DIGITAL_CLOCK (comes out analog)
      • +
    • fl_create_bitmap_cursor(), fl_set_cursor_color()
      • +
    • fl_set_dial_angles()
      • +
    • fl_show_oneliner()
      • +
    • fl_set_choice_shortcut(a,b,c)
      • +
    • command log
      • +
    • Only some of file selector is emulated
      • +
    • FL_DATE_INPUT
      • +
    • fl_pup*() (all these functions)
      • +
    • textbox object (should be easy but I had no sample programs)
      • +
    • xyplot object
      • +
    +

    Additional Notes

    + 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: +

    Does Not Run In Background

    + 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. +

    You Cannot Use IRISGL windows or fl_queue

    + 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. +

    None of this works with FLTK. Nor will it compile, the necessary +calls are not in the interface.

    +

    You have to make a subclass of +Fl_Gl_Window and write a draw() method and +handle() method. This may require anywhere from a trivial to a +major rewrite.

    +

    If you draw into the overlay planes you will have to also write a +draw_overlay() method and call redraw_overlay() on the +OpenGL window.

    +

    One easy way to hack your program so it works is to make the +draw() and handle() methods on your window set some +static variables, storing what event happened. Then in the main loop +of your program, call Fl::wait() and then check these +variables, acting on them as though they are events read from +fl_queue.

    +

    You Must Use OpenGL to Draw Everything

    +

    The file <FL/gl.h> defines replacements for a lot of IRISGL +calls, translating them to OpenGL. There are much better translators +available that you might want to investigate.

    +

    You Cannot Make Forms Subclasses

    + Programs that call fl_make_object or directly setting the +handle routine will not compile. You have to rewrite them to use a +subclass of Fl_Widget. It is important to note that the +handle() method is not exactly the same as the handle() + function of Forms. Where a Forms handle() returned non-zero, +your handle() must call do_callback(). And your +handle() must return non-zero if it "understood" the event. +

    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.

    +

    If your subclass draws into the overlay you are in trouble and will +have to rewrite things a lot.

    +

    You Cannot Use <device.h>

    + If you have written your own "free" widgets you will probably get a +lot of errors about "getvaluator". You should substitute: + + + + + + + + + + + +
    FormsFLTK
    MOUSE_XFl::event_x_root()
    MOUSE_YFl::event_y_root()
    LEFTSHIFTKEY,RIGHTSHIFTKEYFl::event_shift()
    CAPSLOCKKEYFl::event_capslock()
    LEFTCTRLKEY,RIGHTCTRLKEYFl::event_ctrl()
    LEFTALTKEY,RIGHTALTKEYFl::event_alt()
    MOUSE1,RIGHTMOUSEFl::event_state()
    MOUSE2,MIDDLEMOUSEFl::event_state()
    MOUSE3,LEFTMOUSEFl::event_state()
    + Anything else in getvaluator and you are on your own... +

    Font Numbers Are Different

    + 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: +
      +
      +fl_font_name(3,"*courier-medium-r-no*");
+fl_font_name(4,"*courier-bold-r-no*");
+fl_font_name(5,"*courier-medium-o-no*");
+fl_font_name(6,"*times-medium-r-no*");
+fl_font_name(7,"*times-bold-r-no*");
+fl_font_name(8,"*times-medium-i-no*");
+fl_font_name(9,"*bookman-light-r-no*");
+fl_font_name(10,"*bookman-demi-r-no*");
+fl_font_name(11,"*bookman-light-i-no*");
+
      +
    + \ No newline at end of file diff --git a/documentation/functions.html b/documentation/functions.html index 9bea40ce4..815d11dd0 100644 --- a/documentation/functions.html +++ b/documentation/functions.html @@ -1,319 +1,241 @@ - - - +

    B - Function Reference

    - -This appendix describes all of the fl_ functions and -Fl:: methods. For a description of the FLTK widgets, see Appendix A. - + This appendix describes all of the fl_ functions and Fl:: + methods. For a description of the FLTK widgets, see +Appendix A.

    Functions

    - -

    int fl_color_chooser(const char*, double &r, double &g, double &b)
    -int fl_color_chooser(const char *, uchar &r, uchar &g, uchar &b)

    - -The double version takes RGB values in the range 0.0 to 1.0. The -uchar version takes RGB values in the range 0 to 255. - -
    - -

    fl_color_chooser() pops up a window to let the user pick an -arbitrary RGB color. They can pick the hue and saturation in the "hue -box" on the left (hold down CTRL to just change the saturation), and -the brighness using the vertical slider. Or they can type the 8-bit -numbers into the RGB Fl_Value_Input fields, or drag the -mouse across them to adjust them. The pull-down menu lets the user set -the input fields to show RGB, HSV, or 8-bit RGB (0 to 255). - -

    This returns non-zero if the user picks ok, and updates the RGB -values. If the user picks cancel or closes the window this returns -zero and leaves RGB unchanged. - -

    If you use the color chooser on an 8-bit screen, it will allocate -all the available colors, leaving you no space to exactly represent -the color the user picks! You can however use fl_rectf() to fill a region with a -simulated color using dithering. - -

    int fl_show_colormap(int oldcol)

    - -fl_show_colormap() pops up a panel of the 256 colors you -can access with fl_color() and lets the -user pick one of them. It returns the new color index, or the old one -if the user types ESC or clicks outside the window. - -
    - -

    void fl_message(const char *, ...)

    - -Displays a printf-style message in a pop-up box with an "OK" -button, waits for the user to hit the button. The message will wrap -to fit the window, or may be many lines by putting \n characters into -it. The enter key is a shortcut for the OK button. - -
    - -

    void fl_alert(const char *, ...)

    - -Same as fl_message() except for the "!" symbol. - -
    - -

    int fl_ask(const char *, ...)

    - -Displays a printf-style message in a pop-up box with an "Yes" and "No" -button and waits for the user to hit a button. The return value is 1 -if the user hits Yes, 0 if they pick No. The enter key is a shortcut -for Yes and ESC is a shortcut for No. - -
    - -

    int fl_choice(const char *q, const char *b0, const char *b1, const char *b2, ...)

    - -Shows the message with three buttons below it marked with the strings -b0, b1, and b2. Returns 0, 1, or 2 -depending on which button is hit. ESC is a shortcut for button 0 and -the enter key is a shortcut for button 1. Notice the "misordered" -position of the buttons. You can hide buttons by passing NULL -as their labels. - -
    - -

    const char *fl_input(const char *label, const char *deflt = 0, ...)

    - -Pops up a window displaying a string, lets the user edit it, and return -the new value. The cancel button returns NULL. The -returned pointer is only valid until the next time fl_input() -is called. Due to back-compatability, the arguments to any printf -commands in the label are after the default value. - -
    - -

    const char *fl_password(const char *label, const char *deflt = 0, ...)

    - -Same as fl_input() except an Fl_Secret_Input field is used. - -
    - -

    void fl_message_font(Fl_Font fontid, uchar size)

    - -Change the font and font size used for the messages in all the popups. - -

    Fl_Widget *fl_message_icon()

    - -Returns a pointer to the box at the left edge of all the popups. You -can alter the font, color, or label (including making it a Pixmap), -before calling the functions. - -

    char *fl_file_chooser(const char * message, const char *pattern, const char *fname)

    - -FLTK provides a "tab completion" file chooser that makes it easy to -choose files from large directories. This file chooser has several -unique features, the major one being that the Tab key completes -filenames like it does in Emacs or tcsh, and the list always shows all -possible completions. - -
    - -fl_file_chooser() pops up the file chooser, waits for the user -to pick a file or Cancel, and then returns a pointer to that filename -or NULL if Cancel is chosen. - -

    message is a string used to title the window. - -

    pattern is used to limit the files listed in a directory to -those matching the pattern. This matching is done by filename_match(). Use -NULL to show all files. - -

    fname is a default filename to fill in the chooser with. If -this is NULL then the last filename that was choosen is used (unless -that had a different pattern, in which case just the last directory -with no name is used). The first time the file chooser is called this -defaults to a blank string. - -

    The returned value points at a static buffer that is only good -until the next time fl_file_chooser() is called. - -

    void fl_file_chooser_callback(void (*cb)(const char *))

    - -Set a function that is called every time the user clicks a file in the -currently popped-up file chooser. This could be used to preview the -contents of the file. It has to be reasonably fast, and cannot create -FLTK windows. - -

    int filename_list(const char *d, dirent ***list)

    - -This is a portable and const-correct wrapper for the -fl_scandir function. d is the name of a directory -(it does not matter if it has a trailing slash or not). For each file -in that directory a "dirent" structure is created. The only portable -thing about a dirent is that dirent.d_name is the nul-terminated file -name. An array of pointers to these dirents is created and a pointer -to the array is returned in *list. The number of entries is -given as a return value. If there is an error reading the directory a -number less than zero is returned, and errno has the reason -(errno does not work under WIN32). The files are sorted in -"alphanumeric" order, where an attempt is made to put unpadded numbers -in consecutive order. - -

    You can free the returned list of files with the following code: - -

     +

    int filename_isdir(const char *f)

    + Returns non-zero if the file exists and is a directory. +

    const char *filename_name(const char *f)

    + Returns a pointer to the character after the last slash, or to the +start of the filename if there is none. +

    const char *filename_ext(const char *f)

    + Returns a pointer to the last period in filename_name(f), or +a pointer to the trailing nul if none. +

    char *filename_setext(char *f, const char +*ext)

    + Does strcpy(filename_ext(f), ext ? ext : ""). Returns a +pointer to f. +

    int filename_expand(char *out, const char +*in)

    + Splits in at each slash character. Replaces any occurrance +of $X with getenv("X") (leaving it as $X if +the environment variable does not exist). Replaces any occurances of +~X with user X's home directory (leaving it as ~X + if the user does not exist). Any resulting double slashes cause +everything before the second slash to be deleted. Copies the result to +out (in and out may be the same buffer). + Returns non-zero if any changes were made. In true retro +programming style, it is up to you to provide a buffer big enough for +the result. 1024 characters should be enough. +

    int filename_absolute(char *out, const +char *in)

    + If in does not start with a slash, this prepends the current +working directory to in and then deletes any occurances of +. and x/.. from the result, which it copies to out (in + and out may be the same buffer). Returns non-zero if any +changes were made. In true retro programming style, it is up to you +to provide a buffer big enough for the result. 1024 characters should +be enough. +

    int filename_match(const char *f, const char +*pattern)

    + Returns true if f matches pattern. The following +syntax is used by pattern: +

    Fl:: Methods

    - -

    static void Fl::add_fd(int fd, void (*cb)(int, void *), void * = 0)
    -static void Fl::add_fd(int fd, int when, void (*cb)(int, void *), void * = 0)
    -static void Fl::remove_fd(int)

    - -Add file descriptor fd to listen to. When the fd -becomes ready for reading the callback is done. The callback is passed -the fd and the arbitrary void * argument. -Fl::wait() will return immediately after calling the callback. - -

    The second version takes a when bitfield, with the bits -FL_READ, FL_WRITE, and FL_EXCEPT defined, to -indicate when the callback should be done. - -

    There can only be one callback of each type for a file descriptor. -Fl::remove_fd() gets rid of all the callbacks for a -given file descriptor. - -

    Under UNIX any file descriptor can be monitored (files, -devices, pipes, sockets, etc.) Due to limitations in Microsoft Windows, -WIN32 applications can only monitor sockets. - -

    static void Fl::add_handler(int (*f)(int))

    - -Install a function to parse unrecognized events. If FLTK cannot figure -out what to do with an event, it calls each of these functions (most -recent first) until one of them returns non-zero. If none of them -returns non zero then the event is ignored. Events that cause this to -be called are: - - - -

    static Fl::add_idle(void (*cb)(void *), void *)

    - -Adds a callback function that is called by Fl::wait() when there -is nothing to do. This can be used for background -processing. - -

    Warning: this can absorb all your machine's time! - -

    You can have multiple idle callbacks. To remove an idle callback -use Fl::remove_idle(). - -

    Only Fl::wait() calls the idle callbacks. -Fl::wait(time), Fl::check(), and Fl::ready() -ignore them so that these functions may be called by the idle callbacks -themselves without having to worry about recursion. - -

    The idle callback can call any FLTK functions. However if you call -something that calls Fl::wait() (such as a message pop-up) you -should first remove the idle callback so that it does not recurse. - -

    static void Fl::add_timeout(float t, void (*cb)(void *),void *v=0)

    - -Add a one-shot timeout callback. The timeout will happen as soon as -possible after t seconds after the last time wait() -was called. The optional void * argument is passed to the -callback. - -

    This code will print "TICK" each second on stdout, no matter what -else the user or program does: - -

    +

    static void (*Fl::warning)(const char *, ...) +
    static void (*Fl::error)(const char *, ...) +
    static void (*Fl::fatal)(const char *, ...)

    + FLTK will call these to print messages when unexpected conditions +occur. By default they fprintf to stderr, and +Fl::error and Fl::fatal call exit(1). You can +override the behavior by setting the function pointers to your own +routines. +

    Fl::warning means that there was a recoverable problem, the +display may be messed up but the user can probably keep working (all X +protocol errors call this). Fl::error means there is a +recoverable error, but the display is so messed up it is unlikely the +user can continue (very little calls this now). Fl::fatal must +not return, as FLTK is in an unusable state, however your version may +be able to use longjmp or an exception to continue, as long as +it does not call FLTK again.

    + \ No newline at end of file diff --git a/documentation/glut.html b/documentation/glut.html index 643f66dc2..cbfe12a37 100644 --- a/documentation/glut.html +++ b/documentation/glut.html @@ -1,194 +1,145 @@ - - - -

    D - GLUT Compatibility

    - -This appendix describes the GLUT compatibility header file supplied with -FLTK. - + +

    D - GLUT Compatibility

    + This appendix describes the GLUT compatibility header file supplied +with FLTK.

    Using the GLUT Compatibility Header File

    - -You should be able to compile existing GLUT source code by including -<FL/glut.H> instead of <GL/glut.h>. This can -be done by editing the source, by changing the -I switches to -the compiler, or by providing a symbolic link from GL/glut.h -to FL/glut.H. - -

    All files calling GLUT procedures must be compiled with C++. You may -have to alter them slightly to get them to compile without warnings, -and you may have to rename them to get make to use the C++ compiler. - -

    You must link with the FLTK library. If you call any GLUT drawing -functions that FLTK does not emulate -(glutExtensionsSupported(), glutWire*(), -glutSolid*(), and glutStroke*()), you will also have -to link with the GLUT library (after the FLTK library!) - -

    Most of FL/glut.H is inline functions. You should take a -look at it (and maybe at test/glut.cxx in the FLTK source) if -you are having trouble porting your GLUT program. - -

    This has been tested with most of the demo programs that come with -the GLUT 3.3 distribution. - -

    Known Problems

    - -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: - -
      - -
    • glutLayerGet(GLUT_LAYER_IN_USE) -
    • glutLayerGet(GLUT_HAS_OVERLAY) -
    • glutSetColor(), glutGetColor(), glutCopyColormap() -
    • glutInitDisplayMode(GLUT_STEREO) -
    • glutInitDisplayMode(GLUT_LUMINANCE) -
    • glutPushWindow() -
    • glutWarpPointer() -
    • Spaceball, buttonbox, dials, tablet functions, - glutDeviceGet() -
    • glutWindowStatusFunc() -
    • glutGet(GLUT_WINDOW_NUM_CHILDREN) -
    • glutGet(GLUT_SCREEN_WIDTH_MM) -
    • glutGet(GLUT_SCREEN_HEIGHT_MM) -
    • glutGet(GLUT_ELAPSED_TIME) -
    • glutVideoResize() missing. - -
    - -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 GLUT_DOWN and GLUT_UP, mouse -buttons GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON, -GLUT_RIGHT_BUTTON, and GLUT_KEY_F1 thru -F12. - -

    The strings passed as menu labels are not copied. - -

    glutPostRedisplay() does not work if called from -inside a display function. You must use glutIdleFunc() -if you want your display to update continuously. - -

    glutSwapBuffers() does not work from inside a display -function. This is on purpose, because FLTK swaps the buffers for you. - -

    glutUseLayer() does not work well, and should only be -used to initialize transformations inside a resize callback. You -should redraw overlays by using glutOverlayDisplayFunc(). - -

    Overlays are cleared before the overlay display function is called. -glutLayerGet(GLUT_OVERLAY_DAMAGED) always returns true for -compatibility with some GLUT overlay programs. You must rewrite your -code so that gl_color() is used to choose colors in an -overlay, or you will get random overlay colors. - -

    glutSetCursor(GLUT_CURSOR_FULL_CROSSHAIR) just -results in a small crosshair. - -

    The fonts used by glutBitmapCharacter() and -glutBitmapWidth() may be different. - -

    glutInit(argc,argv) will consume different switches than GLUT -does. It accepts the switches recognized by Fl::args(), and will accept any -abbreviation of these switches (such as "-di" for "-display"). - -

    Mixing GLUT and FLTK Code

    - -You can make your GLUT window a child of a Fl_Window with the -following scheme. The biggest trick is that GLUT insists on -show()'ing the window at the point it is created, which means the -Fl_Window parent window must already be shown. - -
      - -
    • Don't call glutInit(). - -
    • Create your Fl_Window, and any FLTK widgets. - Leave a blank area in the window for your GLUT window. - -
    • show() the Fl_Window. Perhaps call - show(argc,argv). - -
    • Call window->begin() so that the GLUT window will - be automatically added to it. - -
    • Use glutInitWindowSize() and - glutInitWindowPosition() to set the location in the - parent window to put the GLUT window. - -
    • Put your GLUT code next. It probably does not need many changes. - Call window->end() immediately after the glutCreateWindow()! - -
    • You can call either glutMainLoop(), - Fl::run(), or loop calling Fl::wait() to run - the program. - -
    - -
    - -

    class Fl_Glut_Window

    - -
    - -

    Class Hierarchy

    - -
      -Fl_Gl_Window
+ You should be able to compile existing GLUT source code by including 
+<FL/glut.H> instead of <GL/glut.h>.  This can be done by 
+editing the source, by changing the -I switches to the 
+compiler, or by providing a symbolic link from GL/glut.h to 
+FL/glut.H. 
+
      All files calling GLUT procedures must be compiled with C++. 
+ You may have to alter them slightly to get them to compile without 
+warnings, and you may have to rename them to get make to use the C++ 
+compiler. 
      
+
      You must link with the FLTK library.  If you call any GLUT drawing 
+functions that FLTK does not emulate (glutExtensionsSupported()
+, glutWire*(), glutSolid*(), and glutStroke*()
+), you will also have to link with the GLUT library (after the 
+FLTK library!) 
      
+
      Most of FL/glut.H is inline functions.  You should take a 
+look at it (and maybe at test/glut.cxx in the FLTK source) if 
+you are having trouble porting your GLUT program. 
      
+
      This has been tested with most of the demo programs that come with 
+the GLUT 3.3 distribution. 
      
+
      Known Problems
      
+ 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: 
+
        
+
      • glutLayerGet(GLUT_LAYER_IN_USE)
        • 
+
      • glutLayerGet(GLUT_HAS_OVERLAY)
        • 
+
      • glutSetColor(), glutGetColor(), glutCopyColormap()
        • 
+
      • glutInitDisplayMode(GLUT_STEREO)
        • 
+
      • glutInitDisplayMode(GLUT_LUMINANCE)
        • 
+
      • glutPushWindow()
        • 
+
      • glutWarpPointer()
        • 
+
      • Spaceball, buttonbox, dials, tablet functions, glutDeviceGet()
+
        • 
+
      • glutWindowStatusFunc()
        • 
+
      • glutGet(GLUT_WINDOW_NUM_CHILDREN)
        • 
+
      • glutGet(GLUT_SCREEN_WIDTH_MM)
        • 
+
      • glutGet(GLUT_SCREEN_HEIGHT_MM)
        • 
+
      • glutGet(GLUT_ELAPSED_TIME)
        • 
+
      • glutVideoResize() missing. 
        • 
+
      
+ 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 
+GLUT_DOWN and GLUT_UP, mouse buttons 
+GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON, GLUT_RIGHT_BUTTON, and 
+GLUT_KEY_F1 thru F12. 
+
      The strings passed as menu labels are not copied. 
      
+
      glutPostRedisplay() does not work if called from inside a 
+display function.  You must use glutIdleFunc() if you want 
+your display to update continuously. 
      
+
      glutSwapBuffers() does not work from inside a display 
+function.  This is on purpose, because FLTK swaps the buffers for you. 
      
+
      glutUseLayer() does not work well, and should only be used 
+to initialize transformations inside a resize callback.  You should 
+redraw overlays by using glutOverlayDisplayFunc(). 
      
+
      Overlays are cleared before the overlay display function is called. 
+glutLayerGet(GLUT_OVERLAY_DAMAGED) always returns true for 
+compatibility with some GLUT overlay programs.  You must rewrite your 
+code so that gl_color() is used to choose colors in an 
+overlay, or you will get random overlay colors. 
      
+
      glutSetCursor(GLUT_CURSOR_FULL_CROSSHAIR) just results in a 
+small crosshair. 
      
+
      The fonts used by glutBitmapCharacter() and glutBitmapWidth()
+ may be different. 
      
+
      glutInit(argc,argv) will consume different switches than 
+GLUT does.  It accepts the switches recognized by 
+Fl::args(), and will accept any abbreviation of these 
+switches (such as "-di" for "-display"). 
      
+
      Mixing GLUT and FLTK Code
      
+ You can make your GLUT window a child of a Fl_Window with the 
+following scheme.  The biggest trick is that GLUT insists on show()
+'ing the window at the point it is created, which means the 
+Fl_Window parent window must already be shown. 
+
        
+
      • Don't call glutInit(). 
        • 
+
      • Create your Fl_Window, and any FLTK widgets.  Leave a 
+blank area in the window for your GLUT window. 
        • 
+
      • show() the Fl_Window.  Perhaps call 
+show(argc,argv). 
        • 
+
      • Call window->begin() so that the GLUT window will  be 
+automatically added to it. 
        • 
+
      • Use glutInitWindowSize() and glutInitWindowPosition()
+ to set the location in the  parent window to put the GLUT window. 
        • 
+
      • Put your GLUT code next.  It probably does not need many changes. 
+ Call window->end() immediately after the 
+glutCreateWindow()! 
        • 
+
      • You can call either glutMainLoop(), Fl::run(), or 
+loop calling Fl::wait() to run  the program. 
        • 
+
      
+
      
+
      class Fl_Glut_Window
      
+
      
+
      Class Hierarchy
      
+
-
-
      Include Files
      
-
-
        -#include <FL/glut.H>
-
      
-
-
      Description
      
-
-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.
-
-
      The current GLUT window is available in the global variable
-glut_window.
-
-
      new Fl_Glut_Window(...) is the same as
-glutCreateWindow() except it does not show() the window
-or make the window current.
-
-
      window->make_current() is the same as
-glutSetWindow(number).  If the window has not had
-show() called on it yet, some functions that assumme an OpenGL
-context will not work.  If you do show() the window, call
-make_current() again to set the context.
-
-
      ~Fl_Glut_Window() is the same as
-glutDestroyWindow().
-
-
      Methods
      
-
-
-
-
      Fl_Glut_Window::Fl_Glut_Window(int x, int y, int w, int h, const char *title = 0)
      
-Fl_Glut_Window::Fl_Glut_Window(int w, int h, const char *title = 0)
      
-
-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.
-
-
      virtual Fl_Glut_Window::~Fl_Glut_Window()
      
-
-Destroys the GLUT window.
-
-
-
+   +----Fl_Glut_Window
+
      +
    +

    Include Files

    +
      +
      +#include <FL/glut.H>
+
      +
    +

    Description

    + 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. +

    The current GLUT window is available in the global variable +glut_window.

    +

    new Fl_Glut_Window(...) is the same as +glutCreateWindow() except it does not show() the window +or make the window current.

    +

    window->make_current() is the same as +glutSetWindow(number). If the window has not had show() + called on it yet, some functions that assumme an OpenGL context will +not work. If you do show() the window, call make_current() + again to set the context.

    +

    ~Fl_Glut_Window() is the same as glutDestroyWindow() +.

    +

    Methods

    + +

    +Fl_Glut_Window::Fl_Glut_Window(int x, int y, int w, int h, const char +*title = 0) +
    Fl_Glut_Window::Fl_Glut_Window(int w, int h, const char *title = 0)     +

    + 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. +

    virtual +Fl_Glut_Window::~Fl_Glut_Window()

    + Destroys the GLUT window. \ No newline at end of file diff --git a/documentation/intro.html b/documentation/intro.html index f941e15da..6216c6b47 100644 --- a/documentation/intro.html +++ b/documentation/intro.html @@ -1,263 +1,198 @@ - - - -

    1 - Introduction to FLTK

    - -The Fast Light Tool Kit ("FLTK", pronounced "fulltick") is a LGPL'd C++ -graphical user interface toolkit for X (UNIX®), OpenGL®, and -Microsoft® Windows® NT 4.0, 95, or 98. It was originally -developed by Mr. Bill Spitzak and is currently maintained by a small -group of developers across the world with a central repository in the -US. - -

    History of FLTK

    - -It has always been Bill's belief that the GUI API of all modern systems -is much too high level. Toolkits (even FL) are not what should -be provided and documented as part of an operating system. The system -only has to provide arbitrary shaped but featureless windows, a -powerful set of graphics drawing calls, and a simple unalterable -method of delivering events to the owners of the windows. NeXT (if you -ignored NextStep) provided this, but they chose to hide it and tried to -push their own baroque toolkit instead... - -

    Many of the ideas in FLTK were developed on a NeXT (but not -using NextStep) in 1987 in a C toolkit Bill called "views". Here he -came up with passing events downward in the tree and having the handle -routine return a value indicating the used the event, and the -table-driven menus. In general he was trying to prove that complex UI -ideas could be entirely implemented in a user space toolkit, with no -knowledge or support by the system. - -

    After going to film school for a few years, Bill worked at Sun -Microsystems on the (doomed) NeWS project. Here he found an even -better and cleaner windowing system, and he reimplemented "views" atop -that. NeWS did have an unnecessarily complex method of delivering -events which hurt it. But the designers did admit that perhaps the -user could write just as good of a button as they could, and officially -exposed the lower level interface. - -

    With the death of NeWS Bill realized that he would have to live with -X. The biggest problem with X is the "window manager", which means -that the toolkit can no longer control the window borders or drag the -window around. - -

    At Digital Domain Bill discovered another toolkit, "Forms". Forms was -similar to his work, but provided many more widgets, since it was used -in many real applications, rather then as theoretical work. He decided -to use Forms, except he integrated his table-driven menus into it. -Several very large programs were created using this version of Forms. - -

    The need to switch to OpenGL and GLX, portability, and a desire to -use C++ subclassing required a rewrite of Forms. This produced the -first version of FLTK. The conversion to C++ required so many changes -it made it impossible to recompile any Forms objects. Since it was -incompatible anyway, Bill decided to incorporate his older ideas as -much as possible by simplifying the lower level interface and the event -passing mechanisim. - -

    Bill received permission to release it for free on the Internet, -with the GNU general public license. Response from Internet users -indicated that the Linux market dwarfed the SGI and high-speed GL -market, so he rewrote it to use X for all drawing, greatly speeding it -up on these machines. That is the version you have now. - -

    Digital Domain has since withdrawn support for FLTK. While Bill is -no longer able to actively develop it, he still contributes to FLTK in -his free time and is a part of the FLTK development team. - -

    Features

    - -FLTK was designed to be statically linked. This was done by splitting it -into many small objects and desigining it so that functions that are not -used do not have pointers to them in the parts that are used, and thus -do not get linked in. This allows you to make an easy-to-install program, -or to modify FLTK to the exact requirements of your application, without -worrying about bloat. FLTK works fine as a shared library, though, and -has started being included on Linux distributions. - -

    Here are some of the core features unique to FLTK: - -

      -
    • sizeof(Fl_Widget) == 40 to 48.
      • - -
    • The "core" (the "hello" program compiled & linked with a static FLTK - library using gcc on a 486 and then stripped) is 39.5K.
      • - -
    • A program including every widget is less than 108K. Does not use - macros, templates, multiple inheritance, or exceptions.
      • - -
    • Written directly atop Xlib (or WIN32) for maximum speed, - and carefully optimized for code size and performance.
      • - -
    • Precise low-level compatability between the X11 and WIN32 - version (only about 10% of the code is different).
      • - -
    • Interactive user interface builder program. Output is - human-readable and editable C++ source code.
      • - -
    • Support for the X11 double buffering extension (emulation - if not available and under Windows.)
      • - -
    • Support for X11 overlay hardware (emulation if none and - under WIN32.)
      • - -
    • Very small & fast portable 2-D drawing library to hide - Xlib and WIN32.
      • - -
    • OpenGL/Mesa drawing area widget.
      • - -
    • Support for OpenGL overlay hardware on both X11 and WIN32. - Emulation if none.
      • - -
    • Text input fields with Emacs key bindings, X cut & - paste, and foreign letter compose!
      • - -
    • Compatibility header file for the GLUT library.
      • - -
    • Compatibility header file for the XForms library.
      • - -
    • Much too much to list here...
      • -
    - -

    Licensing

    - -FLTK comes with complete free source code. FLTK is available under the -terms of the GNU Library General Public -License. Contrary to popular belief, it can be used in commercial -software! (Even Bill Gates could use it.) - -

    What Does "FLTK" Mean?

    - -FLTK was originally designed to be compatable with the Forms Library written -for SGI machines. In that library all the functions and structures started -with "fl_". This naming was extended to all new methods and widgets in -the C++ library, and this prefix was taken as the name of the library. -It is almost impossible to search for "FL" on the Internet, due to the -fact that it is also the abbreviation for Florida. After much debating -and searching for a new name for the toolkit, which was already in use -by several people, Bill came up with "FLTK", and even a bogus excuse that -it stands for "The Fast Light Tool Kit". - -

    Building and Installing FLTK Under UNIX

    - -In most cases you can just type "make". This will run configure with -the default of no options and then compile everything. - -

    FLTK uses GNU autoconf to configure itself for your UNIX platform. The -main things that the configure script will look for are the X11, OpenGL -(or Mesa), and JPEG header and library files. Make sure that they -are in the standard include/library locations. - -

    You can run configure yourself to get the exact setup you need. Type -"./configure <options>", where options are: - -

    -
    --enable-debug
    - -
    Enable debugging code & symbols
    - -
    --enable-shared
    - -
    Enable generation of shared libraries
    - -
    --bindir=/path
    - -
    Set the location for executables [default = /usr/local/bin]
    - -
    --libdir=/path
    - -
    Set the location for libraries [default = /usr/local/lib]
    - -
    --includedir=/path
    - -
    Set the location for include files. [default = /usr/local/include]
    - -
    --prefix=/dir
    - -
    Set the directory prefix for files [default = /usr/local]
    -
    - -When the configure script is done you can just run the "make" command. -This will build the library, FLUID tool, and all of the test programs. - -

    To install the library, become root and type "make install". This -will copy the "fluid" executable to "bindir", the header files to "includedir", -and the library files to "libdir". - -

    Building FLTK Under Micrsoft Windows

    - -There are two ways to build FLTK under Microsoft Windows. The first -is to use the Visual C++ 5.0 project files under the "visualc" directory. -Just open (or double-click on) the "fltk.dsw" file to get the whole shebang. - -

    The second method is to use a GNU-based development tool with the files -in the "makefiles" directory. To build using one of these tools simply -copy the appropriate makeinclude and config files to the main directory -and do a make: - -

      -cp makefiles/makeinclude.<env> makeinclude
-cp makefiles/config.<env> config.h
+
+
      1 - Introduction to FLTK
      
+ The Fast Light Tool Kit ("FLTK", pronounced "fulltick") is a LGPL'd 
+C++ graphical user interface toolkit for X (UNIX®), OpenGL®, and 
+Microsoft® Windows® NT 4.0, 95, or 98. It was originally developed by 
+Mr. Bill Spitzak and is currently maintained by a small group of 
+developers across the world with a central repository in the US. 
+
      History of FLTK
      
+ It has always been Bill's belief that the GUI API of all modern 
+systems is much too high level.  Toolkits (even FL) are not what 
+should be provided and documented as part of an operating system.  The 
+system only has to provide arbitrary shaped but featureless windows, a 
+powerful set of graphics drawing calls, and a simple unalterable
+ method of delivering events to the owners of the windows.  NeXT (if 
+you ignored NextStep) provided this, but they chose to hide it and 
+tried to push their own baroque toolkit instead... 
+
      Many of the ideas in FLTK were developed on a NeXT (but not
+ using NextStep) in 1987 in a C toolkit Bill called "views".  Here he 
+came up with passing events downward in the tree and having the handle 
+routine return a value indicating the used the event, and the 
+table-driven menus.  In general he was trying to prove that complex UI 
+ideas could be entirely implemented in a user space toolkit, with no 
+knowledge or support by the system. 
      
+
      After going to film school for a few years, Bill worked at Sun 
+Microsystems on the (doomed) NeWS project.  Here he found an even 
+better and cleaner windowing system, and he reimplemented "views" atop 
+that.  NeWS did have an unnecessarily complex method of delivering 
+events which hurt it.  But the designers did admit that perhaps the 
+user could write just as good of a button as they could, and officially 
+exposed the lower level interface. 
      
+
      With the death of NeWS Bill realized that he would have to live with 
+X.  The biggest problem with X is the "window manager", which means 
+that the toolkit can no longer control the window borders or drag the 
+window around. 
      
+
      At Digital Domain Bill discovered another toolkit, "Forms".  Forms 
+was similar to his work, but provided many more widgets, since it was 
+used in many real applications, rather then as theoretical work.  He 
+decided to use Forms, except he integrated his table-driven menus into 
+it. Several very large programs were created using this version of 
+Forms. 
      
+
      The need to switch to OpenGL and GLX, portability, and a desire to 
+use C++ subclassing required a rewrite of Forms.  This produced the 
+first version of FLTK.  The conversion to C++ required so many changes 
+it made it impossible to recompile any Forms objects.  Since it was 
+incompatible anyway, Bill decided to incorporate his older ideas as 
+much as possible by simplifying the lower level interface and the event 
+passing mechanisim. 
      
+
      Bill received permission to release it for free on the Internet, 
+with the GNU general public license.  Response from Internet users 
+indicated that the Linux market dwarfed the SGI and high-speed GL 
+market, so he rewrote it to use X for all drawing, greatly speeding it 
+up on these machines.  That is the version you have now. 
      
+
      Digital Domain has since withdrawn support for FLTK.  While Bill is 
+no longer able to actively develop it, he still contributes to FLTK in 
+his free time and is a part of the FLTK development team. 
      
+
      Features
      
+ FLTK was designed to be statically linked. This was done by splitting 
+it into many small objects and desigining it so that functions that are 
+not used do not have pointers to them in the parts that are used, and 
+thus do not get linked in. This allows you to make an easy-to-install 
+program, or to modify FLTK to the exact requirements of your 
+application, without worrying about bloat. FLTK works fine as a shared 
+library, though, and has started being included on Linux distributions. 
+
      Here are some of the core features unique to FLTK: 
      
+
        
+
      • sizeof(Fl_Widget) == 40 to 48.
        • 
+
      • The "core" (the "hello" program compiled & linked with a static 
+FLTK  library using gcc on a 486 and then stripped) is 39.5K.
        • 
+
      • A program including every widget is less than 108K.  Does not use 
+ macros, templates, multiple inheritance, or exceptions.
        • 
+
      • Written directly atop Xlib (or WIN32) for maximum speed,  and 
+carefully optimized for code size and performance.
        • 
+
      • Precise low-level compatability between the X11 and WIN32  version 
+(only about 10% of the code is different).
        • 
+
      • Interactive user interface builder program. Output is 
+ human-readable and editable C++ source code.
        • 
+
      • Support for the X11 double buffering extension (emulation  if not 
+available and under Windows.)
        • 
+
      • Support for X11 overlay hardware (emulation if none and  under 
+WIN32.)
        • 
+
      • Very small & fast portable 2-D drawing library to hide  Xlib and 
+WIN32.
        • 
+
      • OpenGL/Mesa drawing area widget.
        • 
+
      • Support for OpenGL overlay hardware on both X11 and WIN32. 
+ Emulation if none.
        • 
+
      • Text input fields with Emacs key bindings, X cut &  paste, and 
+foreign letter compose!
        • 
+
      • Compatibility header file for the GLUT library.
        • 
+
      • Compatibility header file for the XForms library.
        • 
+
      • Much too much to list here...
        • 
+
      
+
      Licensing
      
+ FLTK comes with complete free source code. FLTK is available under the 
+terms of the GNU Library General Public License. 
+Contrary to popular belief, it can be used in commercial software! 
+(Even Bill Gates could use it.) 
+
      What Does "FLTK" Mean?
      
+ FLTK was originally designed to be compatable with the Forms Library 
+written for SGI machines. In that library all the functions and 
+structures started with "fl_". This naming was extended to all new 
+methods and widgets in the C++ library, and this prefix was taken as 
+the name of the library. It is almost impossible to search for "FL" on 
+the Internet, due to the fact that it is also the abbreviation for 
+Florida. After much debating and searching for a new name for the 
+toolkit, which was already in use by several people, Bill came up with 
+"FLTK", and even a bogus excuse that it stands for "The Fast Light Tool 
+Kit". 
+
      Building and Installing FLTK Under UNIX
      
+ In most cases you can just type "make".  This will run configure with 
+the default of no options and then compile everything. 
+
      FLTK uses GNU autoconf to configure itself for your UNIX platform. 
+The main things that the configure script will look for are the X11, 
+OpenGL (or Mesa), and JPEG header and library files.  Make sure that 
+they are in the standard include/library locations. 
      
+
      You can run configure yourself to get the exact setup you need. Type 
+"./configure <options>", where options are: 
      
+
      
+
      --enable-debug
      
+
      Enable debugging code & symbols
      
+
      --enable-shared
      
+
      Enable generation of shared libraries
      
+
      --bindir=/path
      
+
      Set the location for executables [default = /usr/local/bin]
      
+
      --libdir=/path
      
+
      Set the location for libraries [default = /usr/local/lib]
      
+
      --includedir=/path
      
+
      Set the location for include files. [default = /usr/local/include]
      
+
      --prefix=/dir
      
+
      Set the directory prefix for files [default = /usr/local]
      
+
      
+ When the configure script is done you can just run the "make" command. 
+This will build the library, FLUID tool, and all of the test programs. 
+
      To install the library, become root and type "make install".  This 
+will copy the "fluid" executable to "bindir", the header files to 
+"includedir", and the library files to "libdir". 
      
+
      Building FLTK Under Micrsoft Windows
      
+ There are two ways to build FLTK under Microsoft Windows.  The first 
+is to use the Visual C++ 5.0 project files under the "visualc" 
+directory.  Just open (or double-click on) the "fltk.dsw" file to get 
+the whole shebang. 
+
      The second method is to use a GNU-based development tool with the 
+files in the "makefiles" directory.  To build using one of these tools 
+simply copy the appropriate makeinclude and config files to the main 
+directory and do a make: 
      
+
        
+
        +cp makefiles/makeinclude.<env> makeinclude
+cp makefiles/config.<env> config.h
 make
-
      
-
-
      Building FLTK Under OS/2
      
-
-The current OS/2 build requires XFree86 for OS/2 to work.  A native
-Presentation Manager version has not been implemented yet (volunteers are
-welcome!).
-
-
      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:
-
-
        +
        
+
      
+
      Building FLTK Under OS/2
      
+ The current OS/2 build requires XFree86 for OS/2 to work.  A native 
+Presentation Manager version has not been implemented yet (volunteers 
+are welcome!). 
+
      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: 
      
+
        
+
         cp makefiles/Makefile.os2x Makefile
 cp makefiles/makeinclude.os2x makeinclude
 cp makefiles/config.os2x config.h
 make
-
      
-
-
      Internet Resources
      
-
-FLTK is available on the 'net in a bunch of locations:
-
-
      
-
      WWW
      
-
-
      http://fltk.easysw.com
      
-
-
      FTP
      
-
-
      ftp://ftp.easysw.com/pub/fltk
      
-
-
      ftp://ftp.funet.fi/mirrors/ftp.easysw.com/pub/fltk
      
-
-
      ftp.northamerica.net/pub/ESP/fltk
      
-
-
      EMail
      
-
-
      fltk@easysw.com [see instructions below]
      
-
-
      fltk-bugs@easysw.com [for reporting bugs]
      
-
      
-
-To send a message to the FLTK mailing list ("fltk@easysw.com") you must
-first join the list.  Non-member submissions are blocked to avoid
-problems with SPAM...
-
-
      To join the FLTK mailing list, send a message to "majordomo@easysw.com"
-with "subscribe fltk" in the message body. A digest of this list is available
-by subscribing to the "fltk-digest" mailing list.
-
-
      Reporting Bugs
      
-
-To report a bug in FLTK, send an email to "fltk-bugs@easysw.com". Please
-include the FLTK version, operating system & version, and compiler
-that you are using when describing the bug or problem.
-
-
      For general support and questions, please use the FLTK mailing list
-at "fltk@easysw.com".
-
-
-
+
      +
    +

    Internet Resources

    + FLTK is available on the 'net in a bunch of locations: +
    +
    WWW
    +
    http://fltk.easysw.com
    +
    FTP
    +
    ftp://ftp.easysw.com/pub/fltk +
    +
    +ftp://ftp.funet.fi/mirrors/ftp.easysw.com/pub/fltk
    +
    +ftp.northamerica.net/pub/ESP/fltk +
    +
    EMail
    +
    fltk@easysw.com [see +instructions below]
    +
    fltk-bugs@easysw.com [for +reporting bugs]
    +
    + To send a message to the FLTK mailing list ("fltk@easysw.com") you +must first join the list. Non-member submissions are blocked to avoid +problems with SPAM... +

    To join the FLTK mailing list, send a message to +"majordomo@easysw.com" with "subscribe fltk" in the message body. A +digest of this list is available by subscribing to the "fltk-digest" +mailing list.

    +

    Reporting Bugs

    + To report a bug in FLTK, send an email to "fltk-bugs@easysw.com". +Please include the FLTK version, operating system & version, and +compiler that you are using when describing the bug or problem. +

    For general support and questions, please use the FLTK mailing list +at "fltk@easysw.com".

    + \ No newline at end of file diff --git a/documentation/license.html b/documentation/license.html index add40a768..ff88ad13b 100644 --- a/documentation/license.html +++ b/documentation/license.html @@ -1,468 +1,376 @@ - - - -

    G - Software License

    - + +

    G - Software License

    GNU LIBRARY GENERAL PUBLIC LICENSE

    - -

    Version 2, June 1991
    -Copyright (C) 1991 Free Software Foundation, Inc.
    -59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
    -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed.
    -[This is the first released version of the library GPL. It is -numbered 2 because it goes with version 2 of the ordinary GPL.] - +

    Version 2, June 1991 +
    Copyright (C) 1991 Free Software Foundation, Inc. +
    59 Temple Place - Suite 330, Boston, MA 02111-1307, USA +
    Everyone is permitted to copy and distribute verbatim copies of +this license document, but changing it is not allowed. +
    [This is the first released version of the library GPL. It is +numbered 2 because it goes with version 2 of the ordinary GPL.]

    Preamble

    - -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. - -

    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. - -

    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. - -

    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. - -

    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. - -

    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. - -

    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. - -

    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. - -

    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. - -

    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. - -

    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. - -

    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. - -

    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. - -

    Note that it is possible for a library to be covered by the ordinary -General Public License rather than by this special one. - -

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

    - -0. 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". - -

    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. - -

    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".) - -

    "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. - -

    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. - -

    1. 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. - -

    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. - -

    2. 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: - -

    - -a) The modified work must itself be a software library. - -

    b) You must cause the files modified to carry prominent notices -stating that you changed the files and the date of any change. - -

    c) You must cause the whole of the work to be licensed at no -charge to all third parties under the terms of this License. - -

    d) 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. - -

    (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.) - -

    - -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. - -

    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. - -

    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. - -

    3. 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. - -

    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. - -

    This option is useful when you wish to copy part of the code of -the Library into a program that is not a library. - -

    4. 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. - -

    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. - -

    5. 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. - -

    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. - -

    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. - -

    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.) - -

    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. - -

    6. 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. - -

    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: - -

    - -a) 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.) - -

    b) - 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. - -

    c) - 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. - -

    d) - Verify that the user has already received a copy of these - materials or that you have already sent this user a copy. -

    - -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. - -

    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. - -

    7. - 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: - -

    - -a) - 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. - -

    b) - 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. -

    - -8. - 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. - -

    9. - 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. - -

    10. - 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. - -

    11. - 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. - -

    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. - -

    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. - -

    This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - -

    12. - 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. - -

    13. - 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. - -

    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. - -

    14. - 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. - + 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. +

    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.

    +

    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.

    +

    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.

    +

    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.

    +

    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.

    +

    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.

    +

    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.

    +

    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.

    +

    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.

    +

    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.

    +

    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.

    +

    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.

    +

    Note that it is possible for a library to be covered by the ordinary +General Public License rather than by this special one.

    +

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND +MODIFICATION

    +0. 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". +

    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.

    +

    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".)

    +

    "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.

    +

    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.

    +

    1. 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.

    +

    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.

    +

    2. 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:

    +a) The modified work must itself be a software +library. +

    b) You must cause the files modified to carry +prominent notices stating that you changed the files and the date of +any change.

    +

    c) You must cause the whole of the work to be +licensed at no charge to all third parties under the terms of this +License.

    +

    d) 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.

    +

    (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.)

    +
    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.

    +

    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.

    +

    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.

    +

    3. 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.

    +

    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.

    +

    This option is useful when you wish to copy part of the code of the +Library into a program that is not a library.

    +

    4. 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.

    +

    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.

    +

    5. 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.

    +

    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.

    +

    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.

    +

    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.)

    +

    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.

    +

    6. 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.

    +

    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:

    a) 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.) +

    b) 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.

    +

    c) 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.

    +

    d) Verify that the user has already received a copy +of these materials or that you have already sent this user a copy.

    +
    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.

    +

    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.

    +

    7. 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:

    +a) 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. +

    b) 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.

    +
    8. 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.

    +

    9. 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.

    +

    10. 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.

    +

    11. 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.

    +

    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.

    +

    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.

    +

    This section is intended to make thoroughly clear what is believed +to be a consequence of the rest of this License.

    +

    12. 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.

    +

    13. 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.

    +

    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.

    +

    14. 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.

    NO WARRANTY

    - -

    15. - 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. - -

    16. - 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. - +

    15. 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.

    +

    16. 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.

    END OF TERMS AND CONDITIONS

    - - - + \ No newline at end of file diff --git a/documentation/opengl.html b/documentation/opengl.html index f566d30ad..d618815d1 100644 --- a/documentation/opengl.html +++ b/documentation/opengl.html @@ -1,48 +1,33 @@ - - - -

    9 - Using OpenGL

    - -This chapter discusses using FLTK for your OpenGL applications. - -

    Using OpenGL in FLTK

    - -The easiest way to make an OpenGL display is to subclass Fl_Gl_Window. Your subclass must -implement a draw() method which uses OpenGL calls to draw the -display. Your main program should call redraw() when the -display needs to change, and (somewhat later) FLTK will call -draw(). - -

    With a bit of care you can also use OpenGL to draw into normal FLTK -windows. This is mostly useful because you can use Gourand shading for -drawing your widgets. To do this you use the gl_start() and gl_finish() functions around your OpenGL -code. - -

    You must include FLTK's <FL/gl.h> header file. It will include -the file <GL/gl.h>, define some extra drawing functions -provided by FLTK, and include the <windows.h> header file needed -by WIN32 applications. - -

    Making a Subclass of Fl_Gl_Window

    - -To make a subclass of Fl_Gl_Window, you must provide: - -
      - -
    • A class definition. -
    • A draw() method. -
    • A handle() method (if you need to recieve input from - the user). -
    - -

    Defining the Subclass

    - -To define the subclass you just subclass Fl_Gl_Window class: - -
      +
+
      9 - Using OpenGL
      
+ This chapter discusses using FLTK for your OpenGL applications. 
+
      Using OpenGL in FLTK
      
+ The easiest way to make an OpenGL display is to subclass 
+Fl_Gl_Window. Your subclass must implement a draw()
+ method which uses OpenGL calls to draw the display.  Your main program 
+should call redraw() when the display needs to change, and 
+(somewhat later) FLTK will call draw(). 
+
      With a bit of care you can also use OpenGL to draw into normal FLTK 
+windows.  This is mostly useful because you can use Gourand shading for 
+drawing your widgets.  To do this you use the 
+gl_start() and gl_finish()
+ functions around your OpenGL code. 
      
+
      You must include FLTK's <FL/gl.h> header file.  It will 
+include the file <GL/gl.h>, define some extra drawing 
+functions provided by FLTK, and include the <windows.h> header 
+file needed by WIN32 applications. 
      
+
      Making a Subclass of Fl_Gl_Window
      
+ To make a subclass of Fl_Gl_Window, you must provide: 
+
        
+
      • A class definition. 
        • 
+
      • A draw() method. 
        • 
+
      • A handle() method (if you need to recieve input from  the 
+user). 
        • 
+
      
+
      Defining the Subclass
      
+ To define the subclass you just subclass Fl_Gl_Window class: 
+
        
+
         class MyWindow : public Fl_Gl_Window {
   void draw();
   int handle(int);
@@ -51,17 +36,16 @@ public:
   MyWindow(int X, int Y, int W, int H, const char *L)
     : Fl_Gl_Window(X, Y, W, H, L) {}
 };
-
      
-
-The draw() and handle() 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 draw() Method
      
-
-The draw() method is where you actually do your OpenGL drawing:
-
-
        +
        
+
      
+ The draw() and handle() 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 draw() Method
      
+ The draw() method is where you actually do your OpenGL 
+drawing: 
+
        
+
         void MyWindow::draw() {
   if (!valid()) {
     ... set up projection, viewport, etc ...
@@ -70,14 +54,13 @@ void MyWindow::draw() {
   }
   ... draw ...
 }
-
      
-
-
      The handle() Method
      
-
-The handle() method handles mouse and keyboard events for the
-window:
-
-
        +
        
+
      
+
      The handle() Method
      
+ The handle() method handles mouse and keyboard events for the 
+window: 
+
        
+
         int MyWindow::handle(int event) {
   switch(event) {
   case FL_PUSH:
@@ -103,16 +86,16 @@ int MyWindow::handle(int event) {
     return 0;
   }
 }
-
      
-
-When handle() is called, the OpenGL context is not set up!  If your
-display changes, you should call redraw() and let draw() do the work.
-Don't call any OpenGL drawing functions from inside handle()!
-
-
      You can call some OpenGL stuff like hit detection and texture loading
-functions by doing:
-
-
        +
        
+
      
+ When handle() is called, the OpenGL context is not set up! 
+ If your display changes, you should call redraw() and let 
+draw() do the work. Don't call any OpenGL drawing functions from 
+inside handle()! 
+
      You can call some OpenGL stuff like hit detection and texture 
+loading functions by doing: 
      
+
        
+
           case FL_PUSH:
     make_current(); // make OpenGL context current
     if (!valid()) {
@@ -121,154 +104,116 @@ functions by doing:
     }
     ... ok to call NON-DRAWING OpenGL code here, such as hit
     detection, loading textures, etc...
-
      
-
-Your main program can now create one of your windows by doing new
-MyWindow(...).  You can also use fluid by:
-
-
        
-	
      1. Put your class definition in a MyWindow.H file.
-
-	
      2. In fluid create a box object, resize & place where you want.
-
-	
      3. In the control panel, fill in the "class" field with MyWindow.H.
-	This will make fluid produce constructors for your new class.
-
-	
      4. In the "extra code" put #include "MyWindow.H", so
-	that the fluid output file will compile.
-
-
      
-
-You must put glwindow->show() in your main code after calling
-show() on the window containing the OpenGL window.
-
-
      Using OpenGL in Normal FLTK Windows
      
-
-You can put OpenGL code into an Fl_Widget::draw() method or into the code for
-a boxtype or other places with some care.
-
-
      Most important, before you show any windows (including those
-that don't have OpenGL drawing) you must initialize FLTK so that it
-knows it is going to use OpenGL.  You may use any of the symbols
-described for Fl_Gl_Window::mode() to describe
-how you intend to use OpenGL:
-
-
        +
        
+
      
+ Your main program can now create one of your windows by doing new 
+MyWindow(...).  You can also use fluid
+ by: 
+
        
+
      1. Put your class definition in a MyWindow.H file. 
        2. 
+
      2. In fluid create a box object, resize place where you want. 
        3. 
+
      3. In the control panel, fill in the "class" field with MyWindow.H. 
+ This will make fluid produce constructors for your new class. 
        4. 
+
      4. In the "extra code" put #include "MyWindow.H", so  that 
+the fluid output file will compile. 
        5. 
+
      
+ You must put glwindow->show() in your main code after calling 
+show() on the window containing the OpenGL window. 
+
      Using OpenGL in Normal FLTK Windows
      
+ You can put OpenGL code into an Fl_Widget::draw()
+ method or into the code for a boxtype
+ or other places with some care. 
+
      Most important, before you show any windows (including those 
+that don't have OpenGL drawing) you must initialize FLTK so that it 
+knows it is going to use OpenGL.  You may use any of the symbols 
+described for 
+Fl_Gl_Window::mode() to describe how you intend to use OpenGL: 
      
+
        
+
         Fl::gl_visual(FL_RGB);
-
      
-
-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: 
+
        
+
         gl_start();
 ... put your OpenGL code here ...
 gl_finish();
-
      
-
-gl_start() and gl_finish() 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 glScissor() commands.  These also synchronize the
-OpenGL graphics stream with the drawing done by other X, WIN32, or FLTK
-functions.
-
-
      The same context is reused each time.  If your code changes the
-projection transformation or anything else you should use
-glPushMatrix() and glPopMatrix() functions to put the
-state back before calling gl_finish().
-
-
      You may want to use Fl_Window::current()->h() to get
-the drawable height so you can flip the Y coordinates.
-
-
      Unfortunately, there are a bunch of limitations you must adhere to for
-maximum portability:
-
-
        
-
-	
      • You must choose a default visual with Fl::gl_visual().
-
-	
      • You cannot pass FL_DOUBLE to Fl::gl_visual().
-
-	
      • You cannot use Fl_Double_Window or
-	Fl_Overlay_Window.
-
-
      
-
-Do not call gl_start() or gl_finish() when drawing
-into an Fl_Gl_Window!
-
-
      OpenGL drawing functions
      
-
-FLTK provides some useful OpenGL drawing functions.  They can be freely
-mixed with any OpenGL calls, and are defined by including
-<FL/gl.H> (which you should include instead of the OpenGL
-header <GL/gl.h>).
-
-
      void gl_color(Fl_Color)
      
-
-Set the current color to a FLTK color index.  For color-index modes
-it will use fl_xpixel(c), which is only right if this window
-uses the default colormap!
-
-
      void gl_rect(int x, int y, int w, int h)
      
-void gl_rectf(int x, int y, int w, int h)
      
-
-Outline or fill a rectangle with the current color.  If
-ortho() has been called, then the rectangle will exactly fill
-the pixel rectangle passed.
-
-
      void gl_font(Fl_Font fontid, int size)
      
-
-Set the "current OpenGL font" to the same font you get by calling
-fl_font().
-
-
      int gl_height()
      
-int gl_descent()
      
-float gl_width(const char *)
      
-float gl_width(const char *, int n)
      
-float gl_width(uchar)
      
-
-Return information about the current OpenGL font.
-
-
      void gl_draw(const char *)
      
-void gl_draw(const char *, int n)
      
-
-Draw a nul-terminated string or an array of n characters in
-the current OpenGL font at the current glRasterPos.
-
-
      void gl_draw(const char *, int x, int y)
      
-void gl_draw(const char *, int n, int x, int y)
      
-void gl_draw(const char *, float x, float y)
      
-void gl_draw(const char *, int n, float x, float y)
      
-
-Draw a nul-terminated string or an array of n characters in
-the current OpenGL font at the given position.
-
-
      void gl_draw(const char *, int x, int y, int w, int h, Fl_Align)
      
-
-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 fl_draw().
-
-
      Using OpenGL Optimizer with FLTK
      
-
-OpenGL Optimizer 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.
-
-
      OptimizerWindow Class Definition
      
-
-To use OpenGL Optimizer with FLTK you'll need to create a subclass of
-Fl_Gl_Widget that includes several state variables:
-
-
        +
        
+
      
+gl_start() and 
+gl_finish() 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 
+glScissor() commands.  These also synchronize the OpenGL graphics 
+stream with the drawing done by other X, WIN32, or FLTK functions. 
+
      The same context is reused each time.  If your code changes the 
+projection transformation or anything else you should use 
+glPushMatrix() and glPopMatrix() functions to put the 
+state back before calling gl_finish(). 
      
+
      You may want to use Fl_Window::current()->h() to get the 
+drawable height so you can flip the Y coordinates. 
      
+
      Unfortunately, there are a bunch of limitations you must adhere to 
+for maximum portability: 
      
+
        
+
      • You must choose a default visual with 
+Fl::gl_visual(). 
        • 
+
      • You cannot pass FL_DOUBLE to Fl::gl_visual(). 
        • 
+
      • You cannot use Fl_Double_Window or Fl_Overlay_Window
+. 
        • 
+
      
+ Do not call gl_start() or gl_finish() when 
+drawing into an Fl_Gl_Window! 
+
      OpenGL drawing functions
      
+ FLTK provides some useful OpenGL drawing functions.  They can be 
+freely mixed with any OpenGL calls, and are defined by including 
+<FL/gl.H> (which you should include instead of the OpenGL header 
+<GL/gl.h>). 
+
      void gl_color(Fl_Color)
      
+ Set the current color to a FLTK color index. For color-index modes 
+it will use fl_xpixel(c), which is only right if this window 
+uses the default colormap!
+
      void gl_rect(int x, int y, int w, int h)
+
       void gl_rectf(int x, int y, int w, int h)
      
+ Outline or fill a rectangle with the current color.  If ortho()
+ has been called, then the rectangle will exactly fill the pixel 
+rectangle passed. 
+
      void gl_font(Fl_Font fontid, int size)
      
+ Set the "current OpenGL font" to the same font you get by calling 
+fl_font(). 
+
      int gl_height()
+
       int gl_descent()
+
       float gl_width(const char *)
+
       float gl_width(const char *, int n)
+
       float gl_width(uchar)
      
+ Return information about the current OpenGL font. 
+
      void gl_draw(const char *)
+
       void gl_draw(const char *, int n)
      
+ Draw a nul-terminated string or an array of n characters in 
+the current OpenGL font at the current glRasterPos. 
+
      void gl_draw(const char *, int x, int y)
+
       void gl_draw(const char *, int n, int x, int y)
+
       void gl_draw(const char *, float x, float y)
+
       void gl_draw(const char *, int n, float x, float y)
      
+ Draw a nul-terminated string or an array of n characters in 
+the current OpenGL font at the given position. 
+
      void gl_draw(const char *, int x, int y, int w, int h, Fl_Align)
      
+ 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 fl_draw()
+. 
+
      Using OpenGL Optimizer with FLTK
      
+OpenGL Optimizer 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. 
+
      OptimizerWindow Class Definition
      
+ To use OpenGL Optimizer with FLTK you'll need to create a subclass of 
+Fl_Gl_Widget that includes several state variables: 
+
        
+
         class OptimizerWindow : public Fl_Gl_Window {
   csContext *context_; // Initialized to 0 and set by draw()...
   csDrawAction *draw_action_; // Draw action...
@@ -291,33 +236,34 @@ public:
   void camera(csCamera *c) {
     camera_ = c;
     if (context_) {
-      draw_action_->setCamera(camera_);
-      camera_->draw(draw_action_);
+      draw_action_->setCamera(camera_);
+      camera_->draw(draw_action_);
       redraw();
     }
   }
 };
-
      +
      
+
    +
     
+

    The camera() Method

    - -The camera() method sets the camera (projection and viewpoint) -to use when drawing the scene. The scene is redrawn after this call. - -

    The draw() Method

    - -The draw() method performs the needed initialization -and does the actual drawing: - -
      + The camera() method sets the camera (projection and 
+viewpoint) to use when drawing the scene. The scene is redrawn after 
+this call. 
+
      The draw() Method
      
+ The draw() method performs the needed initialization and does 
+the actual drawing: 
+
        
+
         void OptimizerWindow::draw() {
   if (!context_) {
     // This is the first time we've been asked to draw; create the
     // Optimizer context for the scene...
 
     context_ = new csContext(fl_display, fl_visual);
-    context_->ref();
-    context_->makeCurrent(fl_display, fl_window);
+    context_->ref();
+    context_->makeCurrent(fl_display, fl_window);
 
     ... perform other context setup as desired ...    
 
@@ -325,19 +271,19 @@ void OptimizerWindow::draw() {
 
     draw_action_ = new csDrawAction;
     if (camera_) {
-      draw_action_->setCamera(camera_);
-      camera_->draw(draw_action_);
+      draw_action_->setCamera(camera_);
+      camera_->draw(draw_action_);
     }
   }
 
   if (!valid()) {
     // Update the viewport for this context...
-    context_->setViewport(0, 0, w(), h());
+    context_->setViewport(0, 0, w(), h());
   }
 
   // Clear the window...
 
-  context_->clear(csContext::COLOR_CLEAR | csContext::DEPTH_CLEAR,
+  context_->clear(csContext::COLOR_CLEAR | csContext::DEPTH_CLEAR,
                   0.0f,		// Red
 		  0.0f,		// Green
 		  0.0f,		// Blue
@@ -346,15 +292,11 @@ void OptimizerWindow::draw() {
   // Then draw the scene (if any)...
 
   if (scene_)
-    draw_action_->apply(scene_);
+    draw_action_->apply(scene_);
 }
-
      
-
+
      +

    The scene() Method

    - -The scene() method sets the scene to be drawn. The scene is -a collection of 3D objects in a csGroup. The scene is redrawn -after this call. - - - + The scene() method sets the scene to be drawn. The scene is +a collection of 3D objects in a csGroup. The scene is redrawn +after this call. \ No newline at end of file diff --git a/documentation/osissues.html b/documentation/osissues.html index 572d8952c..83f6d6897 100644 --- a/documentation/osissues.html +++ b/documentation/osissues.html @@ -1,271 +1,216 @@ - - - -

    F - Operating System Issues

    - -This appendix describes the X and WIN32 specific interfaces in FLTK. - -

    X-Specific Interface

    - -
      -#include <FL/x.H>
-
    - -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. - -

    Handling Other X Events

    - -

    void Fl::add_handler(int (*f)(int))

    - -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. - -

    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 fl_xevent variable. - -

    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 FL_SHORTCUT). - -

    extern XEvent *fl_xvent

    - -The most recent X event. - -

    extern ulong fl_event_time

    - -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. - -

    Window fl_xid(const Fl_Window *)

    - -Returns the XID for a window, or zero if not shown(). - -

    Fl_Window *fl_find(ulong xid)

    - -Returns the Fl_Window that corresponds to the given XID, or -NULL if not found. This uses a cache so it is slightly faster -than iterating through the windows yourself. - -

    int fl_handle(const XEvent &)

    - -This call allows you to supply the X events to FLTK, which may allow -FLTK to cooperate with another toolkit or library. The return value -is true if FLTK understood the event (if the window does not belong to -FLTK and the add_handler() functions all ignore it this returns -false). - -

    Besides feeding events your code should call Fl::flush() periodically so that FLTK -redraws its windows. - -

    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 fl_ask(), for -instance) it will not return until the modal function returns. - -

    Drawing using Xlib

    - -The following global variables are set before -Fl_Widget::draw() is called, or by Fl_Window::make_current(): - -
      +
+
      F - Operating System Issues
      
+ This appendix describes the X and WIN32 specific interfaces in FLTK. 
+
      X-Specific Interface
      
+
        
+
        +#include <FL/x.H>
+
        
+
      
+ 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. 
+
      Handling Other X Events
      
+
      void Fl::add_handler(int (*f)(int))
      
+ 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. 
+
      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 fl_xevent variable. 
      
+
      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 FL_SHORTCUT). 
      
+
      extern XEvent *fl_xvent
      
+ The most recent X event. 
+
      extern ulong fl_event_time
      
+ 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. 
+
      Window fl_xid(const Fl_Window *)
      
+ Returns the XID for a window, or zero if not shown(). 
+
      Fl_Window *fl_find(ulong xid)
      
+ Returns the Fl_Window that corresponds to the given XID, or 
+NULL if not found.  This uses a cache so it is slightly faster 
+than iterating through the windows yourself. 
+
      int fl_handle(const XEvent &)
      
+ This call allows you to supply the X events to FLTK, which may allow 
+FLTK to cooperate with another toolkit or library.  The return value is 
+true if FLTK understood the event (if the window does not belong to 
+FLTK and the add_handler() functions all ignore it this 
+returns false). 
+
      Besides feeding events your code should call 
+Fl::flush() periodically so that FLTK redraws its windows. 
      
+
      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 fl_ask(), 
+for instance) it will not return until the modal function returns. 
      
+
      Drawing using Xlib
      
+ The following global variables are set before Fl_Widget::draw()
+ is called, or by 
+Fl_Window::make_current(): 
+
        
+
         extern Display *fl_display;
 extern Window fl_window;
 extern GC fl_gc;
 extern int fl_screen;
 extern XVisualInfo *fl_visual;
 extern Colormap fl_colormap;
-
      
-
-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: 
+
        
+
         XDrawSomething(fl_display, fl_window, fl_gc, ...);
-
      
-
-Other information such as the position or size of the X window can be
-found by looking at Fl_Window::current(), which
-returns a pointer to the Fl_Window being drawn.
-
-
      unsigned long fl_xpixel(Fl_Color i)
      
-unsigned long fl_xpixel(uchar r, uchar g, uchar b)
      
-
-Returns the X pixel number used to draw the given FLTK color index or
-RGB color. This is the X pixel that fl_color() would use.
-
-
      extern XFontStruct *fl_xfont
      
-
-Points at the font selected by the most recent fl_font().  This is not necessarily the
-current font of fl_gc, which is not set until fl_draw() is called.
-
-
      Changing the Display, Screen, or X Visual
      
-
-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
-before the first Fl_Window::show() is called. You may
-also want to call Fl::visual(), which is a
-portable interface to get a full color and/or double buffered visual.
-
-
      int Fl::display(const char *)
      
-
-Set which X display to use.  This actually does
-putenv("DISPLAY=...") so that child programs will display on
-the same screen if called with exec().  This must be done
-before the display is opened.  This call is provided under WIN32 but
-it has no effect.
-
-
      extern Display *fl_display
      
-
-The open X display.  This is needed as an argument to most Xlib calls.
-Don't attempt to change it!  This is NULL before the display is opened.
-
-
      void fl_open_display()
      
-
-Opens the display.  Does nothing if it is already open.  This will make
-sure fl_display is non-zero.  You should call this if you
-wish to do X calls and there is a chance that your code will be called
-before the first show() of a window.
-
-
      This may call Fl::abort() if there is an error opening the display.
-
-
      void fl_close_display()
      
-
-This closes the X connection.  You do not 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.
-
-
      extern int fl_screen
      
-
-Which screen number to use.  This is set by fl_open_display()
-to the default screen.  You can change it by setting this to a
-different value immediately afterwards.  It can also be set by changing
-the last number in the Fl::display() string to "host:0,#".
-
-
      extern XVisualInfo *fl_visual
      
-extern Colormap fl_colormap
      
-
-The visual and colormap that FLTK will use for all windows.  These
-are set by fl_open_display() to the default visual and colormap.  You
-can change them before calling show() on the first window.  Typical
-code for changing the default visual is:
-
-
        +
        
+
      
+ Other information such as the position or size of the X window can be 
+found by looking at 
+Fl_Window::current(), which returns a pointer to the 
+Fl_Window being drawn. 
+
      unsigned long fl_xpixel(Fl_Color i)
+
       unsigned long fl_xpixel(uchar r, uchar g, uchar b)
      
+ Returns the X pixel number used to draw the given FLTK color index or 
+RGB color. This is the X pixel that fl_color()
+ would use. 
+
      extern XFontStruct *fl_xfont
      
+ Points at the font selected by the most recent 
+fl_font().  This is not necessarily the current font of 
+fl_gc, which is not set until fl_draw()
+ is called. 
+
      Changing the Display, Screen, or X Visual
      
+ 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 before the first Fl_Window::show() is called. 
+You may also want to call Fl::visual()
+, which is a portable interface to get a full color and/or double 
+buffered visual. 
+
      int Fl::display(const char *)
      
+ Set which X display to use.  This actually does 
+putenv("DISPLAY=...") so that child programs will display on the 
+same screen if called with exec().  This must be done before 
+the display is opened.  This call is provided under WIN32 but it has no 
+effect. 
+
      extern Display *fl_display
      
+ The open X display.  This is needed as an argument to most Xlib calls. 
+Don't attempt to change it!  This is NULL before the display 
+is opened. 
+
      void fl_open_display()
      
+ Opens the display.  Does nothing if it is already open.  This will 
+make sure fl_display is non-zero.  You should call this if you 
+wish to do X calls and there is a chance that your code will be called 
+before the first show() of a window. 
+
      This may call Fl::abort() if there is an error opening the 
+display. 
      
+
      void fl_close_display()
      
+ This closes the X connection.  You do not 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. 
+
      extern int fl_screen
      
+ Which screen number to use.  This is set by fl_open_display()
+ to the default screen.  You can change it by setting this to a 
+different value immediately afterwards.  It can also be set by changing 
+the last number in the Fl::display() string to "host:0,#". 
+
      extern XVisualInfo *fl_visual
+
      extern Colormap fl_colormap
      
+ The visual and colormap that FLTK will use for all windows.  These are 
+set by fl_open_display() to the default visual and colormap. 
+ You can change them before calling show() on the first 
+window.  Typical code for changing the default visual is: 
+
        
+
         Fl::args(argc, argv); // do this first so $DISPLAY is set
 fl_open_display();
 fl_visual = find_a_good_visual(fl_display, fl_screen);
-if (!fl_visual) Fl::abort("No good visual");
-fl_colormap = make_a_colormap(fl_display, fl_visual->visual, fl_visual->depth);
+if (!fl_visual) Fl::abort("No good visual");
+fl_colormap = make_a_colormap(fl_display, fl_visual->visual, fl_visual->depth);
 // it is now ok to show() windows:
-window->show(argc, argv);
-
      
-
-
      Using a Subclass of Fl_Window for Special X Stuff
      
-
-FLTK can manage an X window on a different screen, visual and/or
-colormap, you just can't use FLTK's drawing routines to draw into it.
-But you can write your own draw() method that uses Xlib
-(and/or OpenGL) calls only.
-
-
      FLTK can also manage XID's provided by other libraries or programs,
-and call those libraries when the window needs to be redrawn.
-
-
      To do this, you need to make a subclass of Fl_Window and override some of these virtual
-functions:
-
-
      virtual void Fl_Window::show()
      
-
-If the window is already shown() this must cause it to be raised,
-this can usually be done by calling Fl_Window::show().  If not shown()
-your implementation must call either Fl_X::set_xid() or
-Fl_X::make_xid().
-
-
      An example:
-
-
        +window->show(argc, argv);
+
        
+
      
+
      Using a Subclass of Fl_Window for Special X Stuff
      
+ FLTK can manage an X window on a different screen, visual and/or 
+colormap, you just can't use FLTK's drawing routines to draw into it. 
+But you can write your own draw() method that uses Xlib 
+(and/or OpenGL) calls only. 
+
      FLTK can also manage XID's provided by other libraries or programs, 
+and call those libraries when the window needs to be redrawn. 
      
+
      To do this, you need to make a subclass of 
+Fl_Window and override some of these virtual functions: 
      
+
      virtual void Fl_Window::show()
      
+ If the window is already shown() this must cause it to be 
+raised, this can usually be done by calling Fl_Window::show(). 
+ If not shown() your implementation must call either 
+Fl_X::set_xid() or Fl_X::make_xid(). 
+
      An example: 
      
+
        
+
         void MyWindow::show() {
   if (shown()) {Fl_Window::show(); return;}  // you must do this!
   fl_open_display();	// necessary if this is first window
-  // we only calcualte the necessary visual & colormap once:
+  // we only calcualte the necessary visual colormap once:
   static XVisualInfo *visual;
   static Colormap colormap;
   if (!visual) {
     visual = figure_out_visual();
     colormap = XCreateColormap(fl_display, RootWindow(fl_display,fl_screen),
-			        vis->visual, AllocNone);
+			        vis->visual, AllocNone);
   }
   Fl_X::make_xid(this, visual, colormap);
 }
-
      
-
-
      Fl_X *Fl_X::set_xid(Fl_Window *, Window xid)
      
-
-Allocate a hidden structure called an Fl_X, put the XID into it, and
-set a pointer to it from the Fl_Window.  This causes
-Fl_Window::shown() to return true.
-
-
      void Fl_X::make_xid(Fl_Window *, XVisualInfo *= fl_visual, Colormap = fl_colormap)
      
-
-This static method does the most onerous parts of creating an X window,
-including setting the label, resize limitations, etc.  It then does
-Fl_X::set_xid() with this new window and maps the window.
-
-
      virtual void Fl_Window::flush()
      
-
-This virtual function is called by Fl::flush() to update the
-window. For FLTK's own windows it does this by setting the global
-variables fl_window and fl_gc and then calling the
-draw() method.  For your own windows you might just want to
-put all the drawing code in here.
-
-
      The X region that is a combination of all damage() calls
-done so far is in Fl_X::i(this)->region.  If NULL
-then you should redraw the entire window.  The undocumented function
-fl_clip_region(XRegion) will initialize the FLTK clip stack
-with a region or NULL for no clipping.  You must set region to
-NULL afterwards as fl_clip_region() now owns it and
-will delete it when done.
-
-
      If damage() & FL_DAMAGE_EXPOSE then only X expose events
-have happened.  This may be useful if you have an undamaged image (such
-as a backing buffer) around.
-
-
      Here is a sample where an undamaged image is kept somewhere:
-
-
        +
        
+
      
+
      Fl_X *Fl_X::set_xid(Fl_Window *, Window xid)
      
+ Allocate a hidden structure called an Fl_X, put the XID into 
+it, and set a pointer to it from the Fl_Window.  This causes 
+Fl_Window::shown() to return true. 
+
      void Fl_X::make_xid(Fl_Window *, XVisualInfo *= fl_visual, Colormap 
+= fl_colormap)
      
+ This static method does the most onerous parts of creating an X 
+window, including setting the label, resize limitations, etc.  It then 
+does Fl_X::set_xid() with this new window and maps the window. 
+
      virtual void Fl_Window::flush()
      
+ This virtual function is called by Fl::flush() to update the 
+window. For FLTK's own windows it does this by setting the global 
+variables fl_window and fl_gc and then calling the 
+draw() method.  For your own windows you might just want to put 
+all the drawing code in here. 
+
      The X region that is a combination of all damage() calls 
+done so far is in Fl_X::i(this)->region.  If NULL
+ then you should redraw the entire window.  The undocumented function 
+fl_clip_region(XRegion) will initialize the FLTK clip stack with a 
+region or NULL for no clipping.  You must set region to 
+NULL afterwards as fl_clip_region() now owns it and will 
+delete it when done. 
      
+
      If damage() FL_DAMAGE_EXPOSE then only X expose events have 
+happened.  This may be useful if you have an undamaged image (such as a 
+backing buffer) around. 
      
+
      Here is a sample where an undamaged image is kept somewhere: 
      
+
        
+
         void MyWindow::flush() {
-  fl_clip_region(Fl_X::i(this)->region);
-  Fl_X::i(this)->region = 0;
+  fl_clip_region(Fl_X::i(this)->region);
+  Fl_X::i(this)->region = 0;
   if (damage() != 2) {... draw things into backing store ...}
   ... copy backing store to window ...
 }
-
      
-
-
      virtual void Fl_Window::hide()
      
-
-Destroy the window server copy of the window.  Usually you will destroy
-contexts, pixmaps, or other resources used by the window, and then call
-Fl_Window::hide() to get rid of the main window identified by
-xid().  If you override this, you must also override the
-destructor as shown:
-
-
        +
        
+
      
+
      virtual void Fl_Window::hide()
      
+ Destroy the window server copy of the window.  Usually you will 
+destroy contexts, pixmaps, or other resources used by the window, and 
+then call Fl_Window::hide() to get rid of the main window 
+identified by xid().  If you override this, you must also 
+override the destructor as shown: 
+
        
+
         void MyWindow::hide() {
   if (mypixmap) {
     XFreePixmap(fl_display,mypixmap);
@@ -273,179 +218,146 @@ void MyWindow::hide() {
   }
   Fl_Window::hide(); // you must call this
 }
-
      
-
-
      virtual void Fl_Window::~Fl_Window()
      
-
-Because of the way C++ works, if you override hide() you must
-override the destructor as well (otherwise only the base class hide()
-is called):
-
-
        +
        
+
      
+
      virtual void Fl_Window::~Fl_Window()
      
+ Because of the way C++ works, if you override hide() you 
+must override the destructor as well (otherwise only the base class 
+hide() is called): 
+
        
+
         MyWindow::~MyWindow() {
   hide();
 }
-
      
-
-
      Setting the Icon of a Window
      
-
-FLTK currently supports setting a window's icon *before* it is shown using
-the Fl_Window::icon() method.
-
-
      void Fl_Window::icon(char *)
      
-
-Sets the icon for the window to the passed pointer.  You will need to
-cast the icon Pixmap to a char * when calling this
-method. To set the icon using a bitmap compiled with your application
-use:
-
-
        -#include "icon.xbm"
+
        
+
      
+
      Setting the Icon of a Window
      
+ FLTK currently supports setting a window's icon *before* it is shown 
+using the Fl_Window::icon() method. 
+
      void Fl_Window::icon(char *)
      
+ Sets the icon for the window to the passed pointer.  You will need to 
+cast the icon Pixmap to a char * when calling this 
+method. To set the icon using a bitmap compiled with your application 
+use: 
+
        
+
        +#include "icon.xbm"
 
 Pixmap p = XCreateBitmapFromData(fl_display, DefaultRootWindow(fl_display),
                                  icon_bits, icon_width, icon_height);
 
-window->icon((char *)p);
-
      - -

      WIN32-Specific Interface

      - -
        -#include <FL/x.H>
-
      - -The <FL/x.H> 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. - -

      Handling Other WIN32 Messages

      - -By default a single WNDCLASSEX called "FLTK" is created. All -Fl_Windows are of this class unless you use -Fl_Window::xclass(). The window class is created the first -time Fl_Window::show() is called. - -

      You can probably combine FLTK with other libraries that make their -own WIN32 window classes. The easiest way is to call Fl::wait(), it -will call DispatchMessage for all messages to the other windows. If -necessary you can let the other library take over (as long as it calls -DispatchMessage()), but you will have to arrange for the function -Fl::flush() to be called regularily so that widgets are updated, -timeouts are handled, and the idle functions are called. - -

      extern MSG fl_msg

      - -The most recent message read by GetMessage (which is called by -Fl::wait(). 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). - -

      void Fl::add_handler(int (*f)(int))

      - -Install a function to parse unrecognized messages sent to FLTK -windows. If FLTK cannot figure out what to do with a message, it -calls each of these functions (most recent first) until one of them -returns non-zero. The argument passed to the fuctions is zero. If -all the handlers return zero then FLTK calls DefWindowProc(). - -

      HWND fl_xid(const Fl_Window *)

      - -Returns the window handle for a Fl_Window, or zero if not -shown(). - -

      Fl_Window *fl_find(HWND xid)

      - -Return the Fl_Window that corresponds to the given window -handle, or NULL if not found. This uses a cache so it is -slightly faster than iterating through the windows yourself. - -

      Drawing Things Using the WIN32 GDI

      - -When the virtual function Fl_Widget::draw() is called, FLTK has -stashed in some global variables all the silly extra arguments you -need to make a proper GDI call. These are: - -
        +window->icon((char *)p);
+
        +
      +

      WIN32-Specific Interface

      +
        +
        +#include <FL/x.H>
+
        +
      + The <FL/x.H> 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. +

      Handling Other WIN32 Messages

      + By default a single WNDCLASSEX called "FLTK" is created. All +Fl_Windows are of this class unless you use Fl_Window::xclass() +. The window class is created the first time Fl_Window::show() + is called. +

      You can probably combine FLTK with other libraries that make their +own WIN32 window classes. The easiest way is to call Fl::wait() +, it will call DispatchMessage for all messages to the other +windows. If necessary you can let the other library take over (as long +as it calls DispatchMessage()), but you will have to arrange +for the function Fl::flush() to be called regularily so that +widgets are updated, timeouts are handled, and the idle functions are +called.

      +

      extern MSG fl_msg

      + The most recent message read by GetMessage (which is called +by Fl::wait(). 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). +

      void Fl::add_handler(int (*f)(int))

      + Install a function to parse unrecognized messages sent to FLTK +windows. If FLTK cannot figure out what to do with a message, it calls +each of these functions (most recent first) until one of them returns +non-zero. The argument passed to the fuctions is zero. If all the +handlers return zero then FLTK calls DefWindowProc(). +

      HWND fl_xid(const Fl_Window *)

      + Returns the window handle for a Fl_Window, or zero if not +shown(). +

      Fl_Window *fl_find(HWND xid)

      + Return the Fl_Window that corresponds to the given window +handle, or NULL if not found. This uses a cache so it is +slightly faster than iterating through the windows yourself. +

      Drawing Things Using the WIN32 GDI

      + When the virtual function Fl_Widget::draw() is called, FLTK +has stashed in some global variables all the silly extra arguments you +need to make a proper GDI call. These are: +
        +
         extern HINSTANCE fl_display;
 extern HWND fl_window;
 extern HDC fl_gc;
 COLORREF fl_RGB();
 HPEN fl_pen();
 HBRUSH fl_brush();
-
      - -These global variables are set before draw() is called, or by Fl_Window::make_current(). You can -refer to them when needed to produce GDI calls. Don't attempt to -change them. The functions return GDI objects for the current color -set by fl_color() and are created as needed and cached. A typical -GDI drawing call is written like this: - -
        +
        +
      + These global variables are set before draw() is called, or by Fl_Window::make_current() +. You can refer to them when needed to produce GDI calls. Don't +attempt to change them. The functions return GDI objects for the +current color set by fl_color() and are created as needed and +cached. A typical GDI drawing call is written like this: +
        +
         DrawSomething(fl_gc, ..., fl_brush());
-
      - -It may also be useful to refer to Fl_Window::current() to get -the window's size or position. - -

      Setting the Icon of a Window

      - -FLTK currently supports setting a window's icon *before* it is shown using -the Fl_Window::icon() method. - -

      void Fl_Window::icon(char *)

      - -Sets the icon for the window to the passed pointer. You will need to -cast the HICON handle to a char * when calling this -method. To set the icon using an icon resource compiled with your -application use: - -
        -window->icon((char *)LoadIcon(fl_display, MAKEINTRESOURCE(IDI_ICON)));
-
      - -

      How to Not Get a MSDOS Console Window

      - -WIN32 has a really stupid mode switch stored in the executables that -controls whether or not to make a console window. - -

      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). - -

      FLTK includes a WinMain() function that calls the ANSI -standard main() entry point for you. This function creates -a console window when you use the debug version of the library. - -

      WIN32 applications without a console cannot write to stdout or -stderr, even if they are run from a console window. Any output -is silently thrown away. - -

      Known Bugs

      - -If a program is deactivated, Fl::wait() does not return until -it is activated again, even though many events are delivered to the -program. This can cause idle background processes to stop -unexpectedly. This also happens while the user is dragging or resizing -windows or otherwise holding the mouse down. I was forced to remove -most of the efficiency FLTK uses for redrawing in order to get windows -to update while being moved. This is a design error in WIN32 and -probably impossible to get around. - -

      Fl_Gl_Window::can_do_overlay() returns true until the first -time it attempts to draw an overlay, and then correctly returns whether -or not there is overlay hardware. - -

      Cut text contains ^J rather than ^M^J to break lines. This is a -feature, not a bug. - -

      SetCapture (used by Fl::grab()) doesn't work, and -the main window title bar turns gray while menus are popped up. - -

      FLUID does not support BMP files yet. - - - + +

    + It may also be useful to refer to +Fl_Window::current() to get the window's size or position. +

    Setting the Icon of a Window

    + FLTK currently supports setting a window's icon *before* it is shown +using the Fl_Window::icon() method. +

    void Fl_Window::icon(char *)

    + Sets the icon for the window to the passed pointer. You will need to +cast the HICON handle to a char * when calling this +method. To set the icon using an icon resource compiled with your +application use: +
      +
      +window->icon((char *)LoadIcon(fl_display, MAKEINTRESOURCE(IDI_ICON)));
+
      +
    +

    How to Not Get a MSDOS Console Window

    + WIN32 has a really stupid mode switch stored in the executables that +controls whether or not to make a console window. +

    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).

    +

    FLTK includes a WinMain() function that calls the ANSI +standard main() entry point for you. This function creates +a console window when you use the debug version of the library.

    +

    WIN32 applications without a console cannot write to stdout + or stderr, even if they are run from a console window. Any +output is silently thrown away.

    +

    Known Bugs

    + If a program is deactivated, Fl::wait() does not return until +it is activated again, even though many events are delivered to the +program. This can cause idle background processes to stop unexpectedly. + This also happens while the user is dragging or resizing windows or +otherwise holding the mouse down. I was forced to remove most of the +efficiency FLTK uses for redrawing in order to get windows to update +while being moved. This is a design error in WIN32 and probably +impossible to get around. +

    Fl_Gl_Window::can_do_overlay() returns true until the first +time it attempts to draw an overlay, and then correctly returns whether +or not there is overlay hardware.

    +

    Cut text contains ^J rather than ^M^J to break lines. This is a +feature, not a bug.

    +

    SetCapture (used by Fl::grab()) doesn't work, and +the main window title bar turns gray while menus are popped up.

    +

    FLUID does not support BMP files yet.

    + \ No newline at end of file diff --git a/documentation/preface.html b/documentation/preface.html index 11df6181d..63781160d 100644 --- a/documentation/preface.html +++ b/documentation/preface.html @@ -1,78 +1,62 @@ - - - - - FLTK 1.0 Programming Manual + +FLTK 1.0 Programming Manual -

    Preface

    - -This manual describes the Fast Light Tool Kit ("FLTK") version 1.0, a C++ Graphical User Interface ("GUI") toolkit for UNIX and Microsoft Windows. Each of the chapters -in this manual is designed as a tutorial for using FLTK, while the appendices provide -a convenient reference for all FLTK widgets, functions, and operating system -interfaces. - + This manual describes the Fast Light Tool Kit ("FLTK") version 1.0, a +C++ Graphical User Interface ("GUI") toolkit for UNIX and Microsoft +Windows. Each of the chapters in this manual is designed as a tutorial +for using FLTK, while the appendices provide a convenient reference for +all FLTK widgets, functions, and operating system interfaces.

    Organization

    - -This manual is organized into the following chapters and appendices: - + This manual is organized into the following chapters and appendices: -

    Conventions

    - -The following typeface conventions are used in this manual: - + The following typeface conventions are used in this manual:
      - -
    • Function and constant names are shown in bold courier type - -
    • Code samples and commands are shown in regular courier type - +
    • Function and constant names are shown in bold courier type +
      • +
    • Code samples and commands are shown in regular courier type
    -

    Abbreviations

    - -The following abbreviations are used in this manual: - + The following abbreviations are used in this manual:
    -
    X11
    -
    The X Window System version 11.
    - -
    Xlib
    -
    The X Window System interface library.
    - -
    WIN32
    -
    The Microsoft Windows 32-bit Application Programmer's Interface.
    +
    X11
    +
    The X Window System version 11.
    +
    Xlib
    +
    The X Window System interface library.
    +
    WIN32
    +
    The Microsoft Windows 32-bit Application Programmer's Interface.
    -

    Copyrights and Trademarks

    - -FLTK is Copyright 1998-1999 by Bill Spitzak and others. Use and distribution of FLTK is -governed by the GNU Library General Public License, located in -Appendix D. - -

    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. - - - + FLTK is Copyright 1998-1999 by Bill Spitzak and others. Use and +distribution of FLTK is governed by the GNU Library General Public +License, located in Appendix D. +

    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.

    + diff --git a/documentation/subclassing.html b/documentation/subclassing.html index 7ed03ed7a..d15f691e2 100644 --- a/documentation/subclassing.html +++ b/documentation/subclassing.html @@ -1,63 +1,51 @@ - - - -

    7 - Adding and Extending Widgets

    - -This chapter describes how to add your own widgets or extend existing -widgets in FLTK. - + +

    7 - Adding and Extending Widgets

    + This chapter describes how to add your own widgets or extend existing +widgets in FLTK.

    Subclassing

    - -New widgets are created by subclassing an existing FLTK widget, -typically Fl_Widget for controls and Fl_Group for -containers. - -

    A control widget typically interacts with the user to receive and/or -display a value of some sort. - -

    A container widget holds a list of child widgets and handles moving, -sizing, showing, or hiding them as needed. Fl_Group is the -main container widget class in FLTK, and all of the other containers -(Fl_Pack, Fl_Scroll, Fl_Tabs, Fl_Tile, -and Fl_Window) are subclasses of it. - -

    You can also subclass other existing widgets to provide a different look -or user-interface. For example, the button widgets are all subclasses of -Fl_Button 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. - + New widgets are created by subclassing an existing FLTK widget, +typically Fl_Widget for controls and Fl_Group for +containers. +

    A control widget typically interacts with the user to receive and/or +display a value of some sort.

    +

    A container widget holds a list of child widgets and handles moving, +sizing, showing, or hiding them as needed. Fl_Group is the +main container widget class in FLTK, and all of the other containers ( +Fl_Pack, Fl_Scroll, Fl_Tabs, Fl_Tile, +and Fl_Window) are subclasses of it.

    +

    You can also subclass other existing widgets to provide a different +look or user-interface. For example, the button widgets are all +subclasses of Fl_Button 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.

    Making a Subclass of Fl_Widget

    - -Your subclasses can directly descend from Fl_Widget or any -subclass of Fl_Widget. Fl_Widget has only four -virtual methods, and overriding some or all of these may be necessary. - + Your subclasses can directly descend from Fl_Widget or any +subclass of Fl_Widget. Fl_Widget has only four +virtual methods, and overriding some or all of these may be necessary.

    The Constructor

    - -The constructor should access the following arguments: - -
      + The constructor should access the following arguments: 
+
        
+
         MyClass(int x, int y, int w, int h, const char *label = 0);
-
      
-
-This will allow the class to be used in Fluid without
-problems.
-
-
      The constructor must call the constructor for the base class and
-pass the same arguments:
-
-
        +
        
+
      
+ This will allow the class to be used in Fluid
+ without problems. 
+
      The constructor must call the constructor for the base class and 
+pass the same arguments: 
      
+
        
+
         MyClass::MyClass(int x, int y, int w, int h, const char *label)
 : Fl_Widget(x, y, w, h, label) {
 // do initialization stuff...
 }
-
      
-
-Fl_Widget's protected constructor sets x(),
-y(), w(), h(), and label() to the
-passed values and initializes the other instance variables to:
-
-
        +
        
+
      
+Fl_Widget's protected constructor sets x(), y()
+, w(), h(), and label() to the passed values 
+and initializes the other instance variables to: 
+
        
+
         type(0);
 box(FL_NO_BOX);
 color(FL_GRAY);
@@ -69,151 +57,118 @@ labelcolor(FL_BLACK);
 align(FL_ALIGN_CENTER);
 callback(default_callback,0);
 flags(ACTIVE|VISIBLE);
-
      
-
+
      +

    Protected Methods of Fl_Widget

    - -The following methods are provided for subclasses to use: - - - -

    void Fl_Widget::damage(uchar mask)
    -void Fl_Widget::damage(uchar mask, int x, int y, int w, int h)
    -uchar Fl_Widget::damage()

    - -The first form indicates that a partial update of the object is -needed. The bits in mask are OR'd into damage(). Your -draw() routine can examine these bits to limit what it is -drawing. The public method Fl_Widget::redraw() simply does -Fl_Widget::damage(FL_DAMAGE_ALL). - -

    The second form indicates that a region is damaged. If only these -calls are done in a window (no calls to damage(n)) then FLTK + The following methods are provided for subclasses to use: +

    +

    void Fl_Widget::damage(uchar mask) +
    void Fl_Widget::damage(uchar mask, int x, int y, int w, int h) +
    uchar Fl_Widget::damage()

    + The first form indicates that a partial update of the object is +needed. The bits in mask are OR'd into damage(). Your +draw() routine can examine these bits to limit what it is drawing. + The public method Fl_Widget::redraw() simply does +Fl_Widget::damage(FL_DAMAGE_ALL). +

    The second form indicates that a region is damaged. If only these +calls are done in a window (no calls to damage(n)) then FLTK will clip to the union of all these calls before drawing anything. -This can greatly speed up incremental displays. The mask bits are or'd -into damage() unless this is a Fl_Window widget. - -

    The third form returns the bitwise-OR of all damage(n) -calls done since the last draw(). The public method -redraw() does damage(FL_DAMAGE_ALL), but the -implementation of your widget can call the private damage(n). - -

    void Fl_Widget::draw_box() const
    -    void Fl_Widget::draw_box(Fl_Boxtype b, ulong c) const

    - -The first form draws this widget's box(), using the dimensions -of the widget. - -The second form uses b as the box type and c as the -color for the box. - -

    void Fl_Widget::draw_label() const
    -void Fl_Widget::draw_label(int x, int y, int w, int h) const
    -void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Align align) const

    - -This is the usual function for a draw() method to call to draw -the widget's label. It does not draw the label if it is supposed to be -outside the box (on the assumption that the enclosing group will draw -those labels). - -

    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, such as a moving slider. - -

    The third form draws the label anywhere. It acts as though -FL_ALIGN_INSIDE has been forced on, the label will appear -inside the passed bounding box. This is designed for parent groups to -draw labels with. - -

    void Fl_Widget::set_flag(SHORTCUT_LABEL)

    - -If your constructor calls this it modifies draw_label() so -that '&' characters cause an underscore to be printed under the next -letter. - -

    void Fl_Widget::set_visible()
    -void Fl_Widget::clear_visible()

    - -Fast inline versions of Fl_Widget::hide() and -Fl_Widget::show(). These do not send the FL_HIDE and -FL_SHOW events to the widget. - -

    int Fl_Widget::test_shortcut() const
    -static int Fl_Widget::test_shortcut(const char *s)

    - -The first version tests Fl_Widget::label() against the current -event (which should be a FL_SHORTCUT event). If the label -contains a '&' character and the character after it matches the key -press, this returns true. This returns false if the -SHORTCUT_LABEL flag is off, if the label is NULL or -does not have a '&' character in it, or if the keypress does not match -the character. - -

    The second version lets you do this test against an arbitrary string. - -

    uchar Fl_Widget::type() const
    -void Fl_Widget::type(uchar t)

    - -The property Fl_Widget::type() can return an arbitrary 8-bit -identifier, and can be set with the protected method type(uchar t). -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. - -

    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. - -

    If you don't have RTTI you can use the clumsy FLTK mechanisim, by -having type() have a unique value. These unique values must -be greater than the symbol FL_RESERVED_TYPE (which is 100). -Look through the header files for FL_RESERVED_TYPE to find an -unused number. If you make a subclass of Fl_Group you must -use FL_GROUP + n, and if you make a subclass of -Fl_Window you must use FL_WINDOW + n (in both cases -n is in the range 1 to 7). - + This can greatly speed up incremental displays. The mask bits are +or'd into damage() unless this is a Fl_Window widget.

    +

    The third form returns the bitwise-OR of all damage(n) + calls done since the last draw(). The public method +redraw() does damage(FL_DAMAGE_ALL), but the +implementation of your widget can call the private damage(n).

    +

    void Fl_Widget::draw_box() const +
    void Fl_Widget::draw_box(Fl_Boxtype b, ulong c) const

    + The first form draws this widget's box(), using the +dimensions of the widget. The second form uses b as the box +type and c as the color for the box. +

    void Fl_Widget::draw_label() const +
    void Fl_Widget::draw_label(int x, int y, int w, int h) const +
    void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Align +align) const

    + This is the usual function for a draw() method to call to +draw the widget's label. It does not draw the label if it is supposed +to be outside the box (on the assumption that the enclosing group will +draw those labels). +

    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, such as a moving slider.

    +

    The third form draws the label anywhere. It acts as though +FL_ALIGN_INSIDE has been forced on, the label will appear inside +the passed bounding box. This is designed for parent groups to draw +labels with.

    +

    void Fl_Widget::set_flag(SHORTCUT_LABEL)

    + If your constructor calls this it modifies draw_label() so +that ''characters cause an underscore to be printed under the next +letter. +

    void Fl_Widget::set_visible() +
    void Fl_Widget::clear_visible()

    + Fast inline versions of Fl_Widget::hide() and +Fl_Widget::show(). These do not send the FL_HIDE and +FL_SHOW events to the widget. +

    int Fl_Widget::test_shortcut() const +
    static int Fl_Widget::test_shortcut(const char *s)

    + The first version tests Fl_Widget::label() against the +current event (which should be a FL_SHORTCUT event). If the +label contains a ''character and the character after it matches the key +press, this returns true. This returns false if the SHORTCUT_LABEL + flag is off, if the label is NULL or does not have a +''character in it, or if the keypress does not match the character. +

    The second version lets you do this test against an arbitrary +string.

    +

    uchar Fl_Widget::type() const +
    void Fl_Widget::type(uchar t)

    + The property Fl_Widget::type() can return an arbitrary 8-bit +identifier, and can be set with the protected method type(uchar t) +. 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. +

    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.

    +

    If you don't have RTTI you can use the clumsy FLTK mechanisim, by +having type() have a unique value. These unique values must +be greater than the symbol FL_RESERVED_TYPE (which is 100). + Look through the header files for FL_RESERVED_TYPE to find an +unused number. If you make a subclass of Fl_Group you must +use FL_GROUP + n, and if you make a subclass of Fl_Window +you must use FL_WINDOW + n (in both cases n is in the +range 1 to 7).

    Handling Events

    - -The virtual method int Fl_Widget::handle(int event) is called -to handle each event passed to the widget. It can: - -
      -
    • Change the state of the widget. - -
    • Call Fl_Widget::redraw() - if the widget needs to be redisplayed. - -
    • Call Fl_Widget::damage(n) if - the widget needs a partial-update (assumming you provide - support for this in your Fl_Widget::draw() method). - -
    • Call Fl_Widget::do_callback() - if a callback should be generated. - -
    • Call Fl_Widget::handle() on child widgets. -
    - -Events are identified by the integer argument. Other information about -the most recent event is stored in static locations and aquired by -calling the Fl::event_*() functions. -This information remains valid until another event is handled. - -

    Here is a sample handle() method for a widget that acts as a -pushbutton and also accepts the keystroke 'x' to cause the callback: - -

      + The virtual method int Fl_Widget::handle(int event) is called 
+to handle each event passed to the widget. It can: 
+
        
+
      • Change the state of the widget. 
        • 
+
      • Call Fl_Widget::redraw()
+ if the widget needs to be redisplayed. 
        • 
+
      • Call 
+Fl_Widget::damage(n) if  the widget needs a partial-update 
+(assumming you provide  support for this in your Fl_Widget::draw()
+ method). 
        • 
+
      • Call 
+Fl_Widget::do_callback() if a callback should be generated. 
        • 
+
      • Call Fl_Widget::handle() on child widgets. 
        • 
+
      
+ Events are identified by the integer argument.  Other information 
+about the most recent event is stored in static locations and aquired 
+by calling the Fl::event_*()
+ functions. This information remains valid until another event is 
+handled. 
+
      Here is a sample handle() method for a widget that acts as 
+a pushbutton and also accepts the keystroke 'x' to cause the callback: 
      
+
        
+
         int MyClass::handle(int event) {
   switch(event) {
     case FL_PUSH:
@@ -247,75 +202,63 @@ int MyClass::handle(int event) {
       return 0;
   }
 }
-
      
-
-You must return non-zero if your handle() method uses the
-event. If you return zero it indicates to the parent widget that it can
-try sending the event to another widget.
-
+
      +
    + You must return non-zero if your handle() method uses the +event. If you return zero it indicates to the parent widget that it can +try sending the event to another widget.

    Drawing the Widget

    - -The draw() virtual method is called when FLTK wants you to -redraw your widget. It will be called if and only if damage() -is non-zero, and damage() will be cleared to zero after it -returns. draw() should be declared protected, so that it can't -be called from non-drawing code. - -

    damage() contains the bitwise-OR of all the damage(n) calls to this -widget since it was last drawn. This can be used for minimal update, -by only redrawing the parts whose bits are set. FLTK will turn -all the bits on if it thinks the entire widget must be redrawn -(for instance due to an expose event). - -

    Expose events (and the above damage(b,x,y,w,h)) will cause -draw() to be called with FLTK's clipping turned on. You can greatly speed up -redrawing in some cases by testing fl_clipped and -fl_current_clip and skipping invisible parts. - -

    Besides the protected methods described above, FLTK provide a large -number of basic drawing functions, which are described below. - + The draw() virtual method is called when FLTK wants you to +redraw your widget. It will be called if and only if damage() + is non-zero, and damage() will be cleared to zero after it +returns. draw() should be declared protected, so that it can't +be called from non-drawing code. +

    damage() contains the bitwise-OR of all the damage(n) + calls to this widget since it was last drawn. This can be used for +minimal update, by only redrawing the parts whose bits are set. FLTK +will turn all the bits on if it thinks the entire widget must be +redrawn (for instance due to an expose event).

    +

    Expose events (and the above damage(b,x,y,w,h)) will cause +draw() to be called with FLTK's +clipping turned on. You can greatly speed up redrawing in some +cases by testing fl_clipped and fl_current_clip and +skipping invisible parts.

    +

    Besides the protected methods described above, FLTK provide a large +number of basic drawing functions, which are described +below.

    Resizing the Widget

    - -The resize(int x, int y, int w, int h) method is called when -the widget is being resized or moved. The arguments are the new -position, width, and height. x(), y(), w(), -and h() still remain the old size. You must call -resize() on your base class with the same arguments to get the -widget size to actually change. - -

    This should not call redraw(), at least if only the -x() and y() change. This is because group objects -like Fl_Scroll may have a more -efficient way of drawing the new position. - + The resize(int x, int y, int w, int h) method is called when +the widget is being resized or moved. The arguments are the new +position, width, and height. x(), y(), w(), +and h() still remain the old size. You must call resize() + on your base class with the same arguments to get the widget size to +actually change. +

    This should not call redraw(), at least if only the +x() and y() change. This is because group objects like +Fl_Scroll may have a more efficient way of drawing the new +position.

    Making a Composite/Group Widget

    - -A "composite" widget contains one or more "child" widgets. To do this -you should subclass Fl_Group. It is -possible to make a composite object that is not a subclass of -Fl_Group, but you'll have to duplicate the code in Fl_Group -anyways. - -

    Instances of the child widgets may be included in the parent: - -

      + A "composite" widget contains one or more "child" widgets.  To do this 
+you should subclass Fl_Group
+. It is possible to make a composite object that is not a subclass of 
+Fl_Group, but you'll have to duplicate the code in Fl_Group
+ anyways. 
+
      Instances of the child widgets may be included in the parent: 
      
+
        
+
         class MyClass : public Fl_Group {
   Fl_Button the_button;
   Fl_Slider the_slider;
   ...
 };
-
      
-
-The constructor has to initialize these instances.  They are
-automatically add()ed to the group, since the
-Fl_Group constructor does begin().  Don't forget
-to call end() or use the Fl_End
-pseudo-class:
-
-
        +
        
+
      
+ The constructor has to initialize these instances.  They are 
+automatically add()ed to the group, since the Fl_Group
+ constructor does begin(). Don't forget to call end()
+ or use the Fl_End pseudo-class:
+
        
+
         MyClass::MyClass(int x, int y, int w, int h) :
   Fl_Group(x, y, w, h),
   the_button(x + 5, y + 5, 100, 20),
@@ -324,41 +267,41 @@ 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!
 }
-
      
-
-The child widgets need callbacks.  These will be called with a pointer
-to the children, but the widget itself may be found in the
-parent() pointer of the child.  Usually these callbacks can be
-static private methods, with a matching private method:
-
-
        +
        
+
      
+ The child widgets need callbacks.  These will be called with a pointer 
+to the children, but the widget itself may be found in the parent()
+ pointer of the child.  Usually these callbacks can be static private 
+methods, with a matching private method: 
+
        
+
         void MyClass::slider_cb(Fl_Widget* v, void *) { // static method
-  ((MyClass*)(v->parent())->slider_cb();
+  ((MyClass*)(v->parent())->slider_cb();
 }
 void MyClass::slider_cb() { // normal method
-  use(the_slider->value());
+  use(the_slider->value());
 }
-
      
-
-If you make the handle() method, you can quickly pass all the
-events to the children using the Fl_Group::handle() method.
-Note that you don't need to override handle() if your
-composite widget does nothing other than pass events to the children:
-
-
        +
        
+
      
+ If you make the handle() method, you can quickly pass all the 
+events to the children using the Fl_Group::handle() method. 
+Note that you don't need to override handle() if your 
+composite widget does nothing other than pass events to the children: 
+
        
+
         int MyClass::handle(int event) {
   if (Fl_Group::handle(event)) return 1;
   ... handle events that children don't want ...
 }
-
      
-
-If you override draw() you need to draw all the children.  If
-redraw() or damage() is called on a child,
-damage(FL_DAMAGE_CHILD) is done to the group, so this bit of
-damage() can be used to indicate that a child needs to be
-drawn.  It is fastest if you avoid drawing anything else in this case:
-
-
        +
        
+
      
+ If you override draw() you need to draw all the children.  If 
+redraw() or damage() is called on a child, 
+damage(FL_DAMAGE_CHILD) is done to the group, so this bit of 
+damage() can be used to indicate that a child needs to be drawn. 
+ It is fastest if you avoid drawing anything else in this case: 
+
        
+
         int MyClass::draw() {
   Fl_Widget *const*a = array();
   if (damage() == FL_DAMAGE_CHILD) { // only redraw some children
@@ -372,86 +315,62 @@ int MyClass::draw() {
     }
   }
 }
-
      
-
-Fl_Group provides some protected methods to make drawing easier:
-
-
-
-
      void Fl_Group::draw_child(Fl_Widget&)
      
-
-This will force the child's damage() bits all to one and call
-draw() on it, then clear the damage().  You should
-call this on all children if a total redraw of your widget is
-requested, or if you draw something (like a background box) that
-damages the child.  Nothing is done if the child is not
-visible() or if it is clipped.
-
-
      void Fl_Group::draw_outside_label(Fl_Widget&) const
      
-
-Draw the labels that are not drawn by
-draw_label().  If you want more control
-over the label positions you might want to call
-child->draw_label(x,y,w,h,a).
-
-
      void Fl_Group::update_child(Fl_Widget&)
      
-
-Draws the child only if it's damage() is non-zero.  You should
-call this on all the children if your own damage is equal to
-FL_DAMAGE_CHILD.  Nothing is done if the child is not
-visible() or if it is clipped.
-
+
      +
    +Fl_Group provides some protected methods to make drawing +easier: + +

    void Fl_Group::draw_child(Fl_Widget&)

    + This will force the child's damage() bits all to one and call +draw() on it, then clear the damage(). You should call +this on all children if a total redraw of your widget is requested, or +if you draw something (like a background box) that damages the child. + Nothing is done if the child is not visible() or if it is +clipped. +

    void +Fl_Group::draw_outside_label(Fl_Widget&) const

    + Draw the labels that are not drawn by +draw_label(). If you want more control over the label +positions you might want to call child->draw_label(x,y,w,h,a). +

    void Fl_Group::update_child(Fl_Widget&)

    + Draws the child only if it's damage() is non-zero. You +should call this on all the children if your own damage is equal to +FL_DAMAGE_CHILD. Nothing is done if the child is not visible() + or if it is clipped.

    Cut and Paste Support

    - -FLTK provides routines to cut and paste ASCII text (in the future this -may be UTF-8) between applications: - - - - -It may be possible to cut/paste non-ASCII data by using Fl::add_handler(). - + FLTK provides routines to cut and paste ASCII text (in the future this +may be UTF-8) between applications: + + It may be possible to cut/paste non-ASCII data by using +Fl::add_handler().

    Making a subclass of Fl_Window

    - -You may want your widget to be a subclass of Fl_Window. This -can be useful if your widget wants to occupy an entire window, and can -also be used to take advantage of system-provided clipping, or to work -with a library that expects a system window id to indicate where to -draw. - -

    Subclassing Fl_Window is almost exactly like subclassing -Fl_Widget, in fact you can easily switch a subclass back and -forth. Watch out for the following differences: - -

      - -
    1. Fl_Window is a subclass of Fl_Group so - make sure your constructor calls end() (unless - you actually want children added to your window). - -
    2. When handling events and drawing, the upper-left corner is - at 0,0, not x(),y() as in other Fl_Widgets. - For instance, to draw a box around the widget, call - draw_box(0, 0, w(), h()), rather than - draw_box( x(), y(), w(), h()). - -
    - -You may also want to subclass Fl_Window in order to get access to -different visuals or to change other attributes of the windows. See -Appendix F - Operating System Issues for more -information. - - - - + You may want your widget to be a subclass of Fl_Window. This +can be useful if your widget wants to occupy an entire window, and can +also be used to take advantage of system-provided clipping, or to work +with a library that expects a system window id to indicate where to +draw. +

    Subclassing Fl_Window is almost exactly like subclassing +Fl_Widget, in fact you can easily switch a subclass back and +forth. Watch out for the following differences:

    +
      +
    1. Fl_Window is a subclass of Fl_Group so make +sure your constructor calls end() (unless you actually +want children added to your window).
      2. +
    2. When handling events and drawing, the upper-left corner is at 0,0, +not x(),y() as in other Fl_Widgets. For instance, to +draw a box around the widget, call draw_box(0, 0, w(), h()), +rather than draw_box( x(), y(), w(), h()).
      3. +
    + You may also want to subclass Fl_Window in order to get +access to different visuals or to change other attributes of the +windows. See Appendix F - Operating +System Issues for more information. \ No newline at end of file diff --git a/documentation/widgets.html b/documentation/widgets.html index 84fc7de1d..ccebf0e97 100644 --- a/documentation/widgets.html +++ b/documentation/widgets.html @@ -1,11 +1,76 @@ - - +

    A - Widget Reference

    -This appendix describes all of the widget classes in FLTK. For a -description of the fl_ functions and Fl:: methods, -see Appendix B. +This appendix describes all of the widget classes in FLTK. For a +description of the fl_ functions and Fl:: methods, +see Appendix B. - - +

    List of Classes

    +
    + + + + + +
    + +Fl_Hold_Browser
    +Fl_Input
    +Fl_Input_
    +Fl_Int_Input
    +Fl_Light_Button
    +Fl_Menu_
    +Fl_Menu_Bar
    +Fl_Menu_Button
    +Fl_Menu_Item
    +Fl_Menu_Window
    +Fl_Multi_Browser
    +Fl_Multiline_Input
    +Fl_Multiline_Output
    +Fl_Output
    +Fl_Overlay_Window
    +Fl_Pack
    +Fl_Positioner
    +Fl_Repeat_Button
    +    		 +Fl_Return_Button
    +Fl_Roller
    +Fl_Round_Button
    +Fl_Scroll
    +Fl_Scrollbar
    +Fl_Secret_Input
    +Fl_Select_Browser
    +Fl_Single_Window
    +Fl_Slider
    +Fl_Tabs
    +Fl_Tile
    +Fl_Timer
    +Fl_Valuator
    +Fl_Value_Input
    +Fl_Value_Output
    +Fl_Value_Slider
    +Fl_Widget
    +Fl_Window
    +
    + +