From 2d6a98560e1f3f027180be34cfc625eabfb32f05 Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Sun, 6 Jan 2002 13:40:32 +0000 Subject: Doco and dist file updates. Add fltk-config man page. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@1911 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/Makefile | 10 +- documentation/fltk-config.man | 83 ++++++++ documentation/fltk.book | 2 +- documentation/fltk.man | 65 ++++-- documentation/fluid.html | 2 +- documentation/fluid.man | 39 ++-- documentation/opengl.html | 457 +++++++++++++++++++++++++----------------- 7 files changed, 437 insertions(+), 221 deletions(-) create mode 100644 documentation/fltk-config.man (limited to 'documentation') diff --git a/documentation/Makefile b/documentation/Makefile index 706c0e4cb..3c033791a 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -1,5 +1,5 @@ # -# "$Id: Makefile,v 1.9.2.10.2.7 2002/01/01 15:11:28 easysw Exp $" +# "$Id: Makefile,v 1.9.2.10.2.8 2002/01/06 13:40:32 easysw Exp $" # # Documentation makefile for the Fast Light Tool Kit (FLTK). # @@ -139,7 +139,7 @@ HTMLFILES = \ subclassing.html \ widgets.html -MANPAGES = fltk.$(CAT3EXT) fluid.$(CAT1EXT) +MANPAGES = fltk.$(CAT3EXT) fltk-config.$(CAT1EXT) fluid.$(CAT1EXT) all: fltk.ps fltk.pdf $(MANPAGES) @@ -165,12 +165,16 @@ install: $(MANPAGES) -mkdir -p $(mandir)/cat1 cp fluid.$(CAT1EXT) $(mandir)/cat1 chmod 644 $(mandir)/cat1/fluid.$(CAT1EXT) + cp fltk-config.$(CAT1EXT) $(mandir)/cat1 + chmod 644 $(mandir)/cat1/fltk-config.$(CAT1EXT) -mkdir -p $(mandir)/cat3 cp fltk.$(CAT3EXT) $(mandir)/cat3 chmod 644 $(mandir)/cat3/fltk.$(CAT3EXT) -mkdir -p $(mandir)/man1 cp fluid.man $(mandir)/man1/fluid.1 chmod 644 $(mandir)/man1/fluid.1 + cp fltk-config.man $(mandir)/man1/fltk-config.1 + chmod 644 $(mandir)/man1/fltk-config.1 -mkdir -p $(mandir)/man3 cp fltk.man $(mandir)/man3/fltk.3 chmod 644 $(mandir)/man3/fltk.3 @@ -203,5 +207,5 @@ fltk.pdf: $(HTMLFILES) $(HTMLDOC) --verbose --batch fltk.book -f fltk.pdf # -# End of "$Id: Makefile,v 1.9.2.10.2.7 2002/01/01 15:11:28 easysw Exp $". +# End of "$Id: Makefile,v 1.9.2.10.2.8 2002/01/06 13:40:32 easysw Exp $". # diff --git a/documentation/fltk-config.man b/documentation/fltk-config.man new file mode 100644 index 000000000..9c1fb7f41 --- /dev/null +++ b/documentation/fltk-config.man @@ -0,0 +1,83 @@ +.TH fltk-config 1 "Fast Light Tool Kit" "6 January 2002" +.SH NAME +fltk-config \- script to get information about the installed version of fltk. +.sp +.SH SYNOPSIS +fltk-config [ --prefix +.I [=DIR] +] [ --exec-prefix +.I [=DIR] +] [ --version ] [ --api-version ] [ --use-gl ] [ --use-images ] [ --use-glut ] +[ --cflags ] [ --cxxflags ] [ --ldflags ] [ --ldstaticflags ] [ --libs ] +[ --compile +.I program.cxx +] [ --post +.I program +] +.SH DESCRIPTION +\fIfltk-config\fR is a utility script that can be used to get information +about the current version of FLTK that is installed on the system, what +compiler and linker options to use when building FLTK-based applications, +and to build simple FLTK applications. +.LP +The following options are supported: +.TP 5 +--api-version +.br +Displays the current FLTK API version number, e.g. "1.1". +.TP 5 +--cflags +.TP 5 +--cxxflags +.br +Displays the C/C++ compiler options to use when compiling source +files that use FLTK. +.TP 5 +--compile \fIprogram.cxx\fR +.br +Compiles the source file \fIprogram.cxx\fR into \fIprogram\fR. +This option implies "--post \fIprogram\fR". +.TP 5 +--ldflags +.br +Displays the linker options to use when linking a FLTK +application. +.TP 5 +--ldstaticflags +.br +Displays the linker options to use when linking a FLTK +application to the static FLTK libraries. +.TP 5 +--libs +.br +Displays the full path to the FLTK library files, to be used for +dependency checking. +.TP 5 +--post \fIprogram\fR +.br +Binds the default FLTK resource fork to a program under MacOS. +Does nothing on other operating systems. +.TP 5 +--use-gl +.br +Enables OpenGL support. +.TP 5 +--use-glut +.br +Enables GLUT support. +.TP 5 +--use-images +.br +Enables image file support. +.TP 5 +--version +.br +Displays the current FLTK version number, e.g. "1.1.0". +.SH SEE ALSO +fluid(1), fltk(3) +.br +FLTK Programming Manual +.br +FLTK Web Site, http://www.fltk.org/ +.SH AUTHORS +Bill Spitzak and others. diff --git a/documentation/fltk.book b/documentation/fltk.book index e9d67b5fb..7b7154822 100644 --- a/documentation/fltk.book +++ b/documentation/fltk.book @@ -8,8 +8,8 @@ editor.html drawing.html events.html subclassing.html -fluid.html opengl.html +fluid.html widgets.html Fl.html Fl_Adjuster.html diff --git a/documentation/fltk.man b/documentation/fltk.man index 14995e78f..2b1387e76 100644 --- a/documentation/fltk.man +++ b/documentation/fltk.man @@ -1,22 +1,55 @@ -.TH fltk 1 "Fast Light Tool Kit" "27 January 2001" +.TH fltk 3 "Fast Light Tool Kit" "6 January 2002" .SH NAME -fltk \- the fast light Tool Kit +fltk \- the fast light tool kit .sp .SH SYNOPSIS - -The Fast Light Tool Kit ("FLTK", pronounced "fulltick") is a LGPL'd -C++ graphical user interface toolkit for X (UNIX(R)), OpenGL(R), and -Microsoft(R) Windows(R) 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. - +The Fast Light Tool Kit ("FLTK", pronounced "fulltick") is a +C++ graphical user interface toolkit for the X Window +System, MacOS(r), and Microsoft Windows(r) that supports OpenGL(r). +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. +.LP +FLTK is provides under the terms of the GNU Library General Public License, +with the following exceptions: +.IP +1. Modifications to the FLTK configure script, config header +file, and makefiles by themselves to support a specific platform +do not constitute a modified or derivative work. +.IP +The authors do request that such modifications be +contributed to the FLTK project - send all +contributions to "fltk-bugs@fltk.org". +.IP +2. Widgets that are subclassed from FLTK widgets do not +constitute a derivative work. +.IP +3. Static linking of applications and widgets to the FLTK +library does not constitute a derivative work and does not +require the author to provide source code for the application or +widget, use the shared FLTK libraries, or link their +applications or widgets against a user-supplied version of FLTK. +.IP +If you link the application or widget to a modified version of +FLTK, then the changes to FLTK must be provided under the terms +of the LGPL in sections 1, 2, and 4. +.IP +4. You do not have to provide a copy of the FLTK license with +programs that are linked to the FLTK library, nor do you have to +identify the FLTK license in your program or documentation as +required by section 6 of the LGPL. +.IP +However, programs must still identify their use of FLTK. The +following example statement can be included in user +documentation to satisfy this requirement: +.IP +[program/widget] is based in part on the work of the FLTK +project (http://www.fltk.org). .SH SEE ALSO -.nf +fltk-config(1), fluid(1) +.br FLTK Programming Manual -file:/usr/local/share/doc/fltk/index.html -.PP -http://www.fltk.org -.PP -.BR fluid (1) -.SH AUTHOR +.br +FLTK Web Site, http://www.fltk.org/ +.SH AUTHORS Bill Spitzak and others. diff --git a/documentation/fluid.html b/documentation/fluid.html index eade5232e..cedda5716 100644 --- a/documentation/fluid.html +++ b/documentation/fluid.html @@ -1,5 +1,5 @@ -

8 - Programming with FLUID

+

9 - Programming with FLUID

This chapter shows how to use the Fast Light User-Interface Designer ("FLUID") to create your GUIs. diff --git a/documentation/fluid.man b/documentation/fluid.man index 0b69440e9..39a8e28fc 100644 --- a/documentation/fluid.man +++ b/documentation/fluid.man @@ -1,27 +1,32 @@ -.TH fluid 1 "Fast Light Tool Kit" "27 January 2001" +.TH fluid 1 "Fast Light Tool Kit" "6 January 2002" .SH NAME fluid \- the fast light user-interface designer .sp .SH SYNOPSIS -.nf -fluid \fI[-c [-o code-filename -h header-filename]] [filename.fl]\fR +fluid [ -c [ -o +.I code-filename +-h +.I header-filename +] ] [ +.I filename.fl +] .fi .SH DESCRIPTION -\fIfluid\fR is an interactive GUI designer for FLTK. When run with no arguments -or with a filename, \fIfluid\fR will display the GUI hierarchy and any windows -defined in the file. Functions, classes, windows, and GUI components can be +\fIfluid\fR is an interactive GUI designer for FLTK. When run +with no arguments or with a filename, \fIfluid\fR will display +the GUI hierarchy and any windows defined in the file. +Functions, classes, windows, and GUI components can be manipulated as needed. .LP -When used with the \fI-c\fR option, \fIfluid\fR will create the necessary C++ -header and code files in the current directory. You can override the default -extensions, filenames, and directories using the \fI-o\fR and \fI-h\fR options. +When used with the \fI-c\fR option, \fIfluid\fR will create the +necessary C++ header and code files in the current directory. +You can override the default extensions, filenames, and +directories using the \fI-o\fR and \fI-h\fR options. .SH SEE ALSO -.nf -FLTK Programming Manual, chapter 8. -file:/usr/local/share/doc/fltk/fluid.html -.PP -http://www.fltk.org -.PP -.BR fltk (3) -.SH AUTHOR +fltk-config(1), fltk(3) +.br +FLTK Programming Manual, Chapter 9 +.br +FLTK Web Site, http://www.fltk.org/ +.SH AUTHORS Bill Spitzak and others. diff --git a/documentation/opengl.html b/documentation/opengl.html index b390e46b9..ee2a2e08f 100644 --- a/documentation/opengl.html +++ b/documentation/opengl.html @@ -1,35 +1,53 @@ - -

9 - Using OpenGL

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

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

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 allows you to use Gouraud 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.

+ +

With a bit of care you can also use OpenGL to draw into +normal FLTK windows. This allows you to use Gouraud shading for +drawing your widgets. To do this you use the 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: + +

To make a subclass of Fl_Gl_Window, you must provide: +

-If your subclass provides static controls in the window, they must be -redrawn whenever the FL_DAMAGE_ALL bit is set in the value -returned by damage(). For double-buffered windows you will -need to surround the drawing code with the following code to make sure -that both buffers are redrawn: - + +
+ + + + +
Note: + +

If you are using the Mesa graphics library, the call + to glDrawBuffer() is not required and will slow + down drawing considerably. The preprocessor instructions + shown above will optimize your code based upon the + graphics library used. + +

+

Defining the Subclass

-To define the subclass you just subclass the Fl_Gl_Window class: - + +

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 handle() Method

- The handle() method handles mouse and keyboard events for the -window: - + +

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:

- + +

Your main program can now create one of your windows by doing +new MyWindow(...). You can also use FLUID by: +

    -
  1. Putting your class definition in a MyWindow.H file.
    2. -
  2. Creating a Fl_Box widget in FLUID.
    3. -
  3. In the widget panel fill in the "class" field with MyWindow. -This will make FLUID produce constructors for your new class.
    4. -
  4. In the "Extra Code" field put #include "MyWindow.H", so that -the FLUID output file will compile.
    5. + +
  5. Putting your class definition in a + MyWindow.H file.
    6. + +
  6. Creating a Fl_Box widget in FLUID.
    7. + +
  7. In the widget panel fill in the "class" + field with MyWindow. This will make FLUID + produce constructors for your new class.
    8. + +
  8. In the "Extra Code" field put #include + "MyWindow.H", so that the FLUID output + file will compile.
    9. +
-You must put glwindow->show() in your main code after calling -show() on the window containing the OpenGL window. + +

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

- + +

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 functions 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 that you can flip the Y +coordinates.

+ +

Unfortunately, there are a bunch of limitations you must +adhere to for maximum portability:

+ -Do not call gl_start() or gl_finish() when -drawing into an Fl_Gl_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>). + +

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. For color-index modes -it will use fl_xpixel(c), which is only right if this window -uses the default colormap! + +

Sets the current OpenGL color to a FLTK color. 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 -Fl_Gl_Window::ortho() +
void gl_rectf(int x, int y, int w, int h) + +

Outlines or fills a rectangle with the current color. If Fl_Gl_Window::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(). + +

Sets 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. +
int gl_descent() +
float gl_width(const char *) +
float gl_width(const char *, int n) +
float gl_width(uchar) + +

Returns 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 raster position. +
void gl_draw(const char *, int n) + +

Draws a nul-terminated string or an array of n +characters in the current OpenGL font at the current raster +position. +

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

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

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

Speeding up OpenGL

-Performance of Fl_Gl_Window may be improved on some types of OpenGL -implementations (in particular MESA or other software emulators) by -setting the GL_SWAP_TYPE environment variable. This variable -declares what is in the back buffer after you do a swapbuffers. +

Performance of Fl_Gl_Window may be improved on some types of +OpenGL implementations, in particular MESA and other software +emulators, by setting the GL_SWAP_TYPE environment +variable. This variable declares what is in the backbuffer after +you do a swapbuffers.

-

This is easily tested by running the gl_overlay demo program and -seeing if the display is correct when you drag another window over -it or if you drag the window off the screen and back on. You have to -exit and run the program again for it to see any changes to the -environment variable. +

This is easily tested by running the gl_overlay demo +program and seeing if the display is correct when you drag +another window over it or if you drag the window off the screen +and back on. You have to exit and run the program again for it +to see any changes to the environment variable.

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

OpenGL +Optimizer is a scene graph toolkit for OpenGL available from +Silicon Graphics for IRIX and Microsoft Windows. 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: -

The camera() Method

- The camera() method sets the camera (projection and + +

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 draw() method performs the needed initialization and does the actual drawing: -

+

The scene() Method

- The scene() method sets the scene to be drawn. The scene is + +

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. +after this call. + + + -- cgit v1.2.3