more html to doxygen conversion for {enumerations,glut,forms}.dox

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6408 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

1 files changed, 152 insertions, 106 deletions

diff --git a/documentation/glut.dox b/documentation/glut.dox
index cdbb1616e..9d1e32898 100644
--- a/documentation/glut.dox
+++ b/documentation/glut.dox
@@ -2,117 +2,155 @@
 
  \page	glut	D - GLUT Compatibility
 
-<P>This appendix describes the GLUT compatibility header file supplied with FLTK. FLTK's GLUT compatibility is based on the original GLUT 3.7 and the follow-on FreeGLUT 2.4.0 libraries.</P>
-<H2>Using the GLUT Compatibility Header File</H2>
-<P>You should be able to compile existing GLUT source code by including <TT><FL/glut.H></TT> instead of <TT><GL/glut.h></TT>.  This can be done by editing the source, by changing the <TT>-I</TT> switches to the compiler, or by providing a symbolic link from <TT>GL/glut.h</TT> to <TT>FL/glut.H</TT>.</P>
-<P><I>All files calling GLUT procedures must be compiled with C++</I>. You may have to alter them slightly to get them to compile without warnings, and you may have to rename them to get make to use the C++ compiler.</P>
-<P>You must link with the FLTK library. Most of <TT>FL/glut.H</TT> is inline functions.  You should take a look at it (and maybe at <TT>test/glpuzzle.cxx</TT> in the FLTK source) if you are having trouble porting your GLUT program. </P>
-<P>This has been tested with most of the demo programs that come with the GLUT and FreeGLUT distributions.</P>
-<H2>Known Problems</H2>
-<P>The following functions and/or arguments to functions are missing, and
-you will have to replace them or comment them out for your code to
-compile:
-<UL>
-<LI><TT>glutGet(GLUT_ELAPSED_TIME)</TT></LI>
-<LI><TT>glutGet(GLUT_SCREEN_HEIGHT_MM)</TT></LI>
-<LI><TT>glutGet(GLUT_SCREEN_WIDTH_MM)</TT></LI>
-<LI><TT>glutGet(GLUT_WINDOW_NUM_CHILDREN)</TT></LI>
-<LI><TT>glutInitDisplayMode(GLUT_LUMINANCE)</TT></LI>
-<LI><TT>glutLayerGet(GLUT_HAS_OVERLAY)</TT></LI>
-<LI><TT>glutLayerGet(GLUT_LAYER_IN_USE)</TT></LI>
-<LI><TT>glutPushWindow()</TT></LI>
-<LI><TT>glutSetColor(), glutGetColor(), glutCopyColormap()</TT></LI>
-<LI><TT>glutVideoResize()</TT> missing. </LI>
-<LI><TT>glutWarpPointer()</TT></LI>
-<LI><TT>glutWindowStatusFunc()</TT></LI>
-<LI>Spaceball, buttonbox, dials, and tablet functions</LI>
-</UL>
- Most of the symbols/enumerations have different values than GLUT uses.
- This will break code that relies on the actual values. The only
-symbols guaranteed to have the same values are true/false pairs like <TT>
-GLUT_DOWN</TT> and <TT>GLUT_UP</TT>, mouse buttons <TT>
-GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON, GLUT_RIGHT_BUTTON</TT>, and <TT>
-GLUT_KEY_F1</TT> thru <TT>F12</TT>.
-<P>The strings passed as menu labels are not copied. </P>
-<P><TT>glutPostRedisplay()</TT> does not work if called from inside a
-display function.  You must use <TT>glutIdleFunc()</TT> if you want
-your display to update continuously. </P>
-<P><TT>glutSwapBuffers()</TT> does not work from inside a display
-function.  This is on purpose, because FLTK swaps the buffers for you. </P>
-<P><TT>glutUseLayer()</TT> does not work well, and should only be used
+This appendix describes the GLUT compatibility header file supplied with
+FLTK. FLTK's GLUT compatibility is based on the original GLUT 3.7 and
+the follow-on FreeGLUT 2.4.0 libraries.
+
+\section glut_using Using the GLUT Compatibility Header File
+
+You should be able to compile existing GLUT source code by including
+<tt><FL/glut.H></tt> instead of <tt><GL/glut.h></tt>.  This can be
+done by editing the source, by changing the <tt>-I</tt> switches to
+the compiler, or by providing a symbolic link from <tt>GL/glut.h</tt>
+to <tt>FL/glut.H</tt>.
+
+<I>All files calling GLUT procedures must be compiled with C++</I>. You
+may have to alter them slightly to get them to compile without warnings,
+and you may have to rename them to get make to use the C++ compiler.
+
+You must link with the FLTK library. Most of <tt>FL/glut.H</tt>
+is inline functions.  You should take a look at it (and maybe at
+<tt>test/glpuzzle.cxx</tt> in the FLTK source) if you are having trouble
+porting your GLUT program.
+
+This has been tested with most of the demo programs that come with
+the GLUT and FreeGLUT distributions.
+
+\section glut_known_problems 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:
+
+\li <tt>glutGet(GLUT_ELAPSED_TIME)</tt>
+\li <tt>glutGet(GLUT_SCREEN_HEIGHT_MM)</tt>
+\li <tt>glutGet(GLUT_SCREEN_WIDTH_MM)</tt>
+\li <tt>glutGet(GLUT_WINDOW_NUM_CHILDREN)</tt>
+\li <tt>glutInitDisplayMode(GLUT_LUMINANCE)</tt>
+\li <tt>glutLayerGet(GLUT_HAS_OVERLAY)</tt>
+\li <tt>glutLayerGet(GLUT_LAYER_IN_USE)</tt>
+\li <tt>glutPushWindow()</tt>
+\li <tt>glutSetColor(), glutGetColor(), glutCopyColormap()</tt>
+\li <tt>glutVideoResize()</tt> missing. 
+\li <tt>glutWarpPointer()</tt>
+\li <tt>glutWindowStatusFunc()</tt>
+\li Spaceball, buttonbox, dials, and tablet functions
+
+Most of the symbols/enumerations have different values than GLUT uses.
+This will break code that relies on the actual values. The only
+symbols guaranteed to have the same values are true/false pairs like <tt>
+GLUT_DOWN</tt> and <tt>GLUT_UP</tt>, mouse buttons <tt>
+GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON, GLUT_RIGHT_BUTTON</tt>, and <tt>
+GLUT_KEY_F1</tt> thru <tt>F12</tt>.
+
+The strings passed as menu labels are not copied.
+
+<tt>glutPostRedisplay()</tt> does not work if called from inside a
+display function.  You must use <tt>glutIdleFunc()</tt> if you want
+your display to update continuously.
+
+<tt>glutSwapBuffers()</tt> does not work from inside a display
+function.  This is on purpose, because FLTK swaps the buffers for you.
+
+<tt>glutUseLayer()</tt> does not work well, and should only be used
 to initialize transformations inside a resize callback.  You should
-redraw overlays by using <TT>glutOverlayDisplayFunc()</TT>. </P>
-<P>Overlays are cleared before the overlay display function is called. <TT>
-glutLayerGet(GLUT_OVERLAY_DAMAGED)</TT> always returns true for
+redraw overlays by using <tt>glutOverlayDisplayFunc()</tt>.
+
+Overlays are cleared before the overlay display function is called. <tt>
+glutLayerGet(GLUT_OVERLAY_DAMAGED)</tt> always returns true for
 compatibility with some GLUT overlay programs.  You must rewrite your
-code so that <TT>gl_color()</TT> is used to choose colors in an
-overlay, or you will get random overlay colors. </P>
-<P><TT>glutSetCursor(GLUT_CURSOR_FULL_CROSSHAIR)</TT> just results in a
-small crosshair. </P>
-<P>The fonts used by <TT>glutBitmapCharacter() and glutBitmapWidth()</TT>
- may be different. </P>
-<P><TT>glutInit(argc,argv)</TT> will consume different switches than
+code so that <tt>gl_color()</tt> is used to choose colors in an
+overlay, or you will get random overlay colors.
+
+<tt>glutSetCursor(GLUT_CURSOR_FULL_CROSSHAIR)</tt> just results in a
+small crosshair.
+
+The fonts used by <tt>glutBitmapCharacter() and glutBitmapWidth()</tt>
+may be different.
+
+<tt>glutInit(argc,argv)</tt> will consume different switches than
 GLUT does.  It accepts the switches recognized by <A href="Fl.html#Fl.args">
-<TT>Fl::args()</TT></A>, and will accept any abbreviation of these
-switches (such as "-di" for "-display"). </P>
-<H2>Mixing GLUT and FLTK Code</H2>
- You can make your GLUT window a child of a <TT>Fl_Window</TT> with the
-following scheme.  The biggest trick is that GLUT insists on <TT>show()</TT>
-'ing the window at the point it is created, which means the <TT>
-Fl_Window</TT> parent window must already be shown.
-<UL>
-<LI>Don't call <TT>glutInit()</TT>. </LI>
-<LI>Create your <TT>Fl_Window</TT>, and any FLTK widgets.  Leave a
-blank area in the window for your GLUT window. </LI>
-<LI><TT>show()</TT> the <TT>Fl_Window</TT>.  Perhaps call <TT>
-show(argc,argv)</TT>. </LI>
-<LI>Call <TT>window->begin()</TT> so that the GLUT window will  be
-automatically added to it. </LI>
-<LI>Use <TT>glutInitWindowSize()</TT> and <TT>glutInitWindowPosition()</TT>
- to set the location in the  parent window to put the GLUT window. </LI>
-<LI>Put your GLUT code next.  It probably does not need many changes.
- Call <TT>window->end()</TT> immediately after the <TT>
-glutCreateWindow()</TT>! </LI>
-<LI>You can call either <TT>glutMainLoop()</TT>, <TT>Fl::run()</TT>, or
-loop calling <TT>Fl::wait()</TT> to run  the program. </LI>
-</UL>
+<tt>Fl::args()</tt></A>, and will accept any abbreviation of these
+switches (such as "-di" for "-display").
+
+\section glut_mixing Mixing GLUT and FLTK Code
+
+You can make your GLUT window a child of a <tt>Fl_Window</tt> with the
+following scheme.  The biggest trick is that GLUT insists on
+<tt>show()</tt>'ing the window at the point it is created, which means the
+<tt>Fl_Window</tt> parent window must already be shown.
+
+\li Don't call <tt>glutInit()</tt>. 
+\li Create your <tt>Fl_Window</tt>, and any FLTK widgets.  Leave a
+    blank area in the window for your GLUT window. 
+\li <tt>show()</tt> the <tt>Fl_Window</tt>.  Perhaps call <tt>
+    show(argc,argv)</tt>. 
+\li Call <tt>window->begin()</tt> so that the GLUT window will  be
+    automatically added to it. 
+\li Use <tt>glutInitWindowSize()</tt> and <tt>glutInitWindowPosition()</tt>
+    to set the location in the  parent window to put the GLUT window. 
+\li Put your GLUT code next.  It probably does not need many changes.
+    Call <tt>window->end()</tt> immediately after the
+    <tt>glutCreateWindow()</tt>! 
+\li You can call either <tt>glutMainLoop()</tt>, <tt>Fl::run()</tt>,
+    or loop calling <tt>Fl::wait()</tt> to run  the program. 
+
 <HR break>
    <A NAME="Fl_Glut_Window"></A> <!-- For old HTML links only ! -->
    \section glut_Fl_Glut_Window class Fl_Glut_Window
 <HR>
-<H3>Class Hierarchy</H3>
+
+\subsection glut_class_hierarchy Class Hierarchy
+
 \code
-<A href=Fl_Gl_Window.html#Fl_Gl_Window>Fl_Gl_Window</A>
+Fl_Gl_Window
    |
-   +----<B>Fl_Glut_Window</B>
+   +----Fl_Glut_Window
 \endcode
 
-<H3>Include Files</H3>
+\subsection glut_include_files Include Files
 
 \code
 #include <FL/glut.H>
 \endcode
 
-<H3>Description</H3>
- Each GLUT window is an instance of this class.  You may find it useful
+\subsection glut_description 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
+These may be created without opening the display, and thus can fit
 better into FLTK's method of creating windows.
-<P>The current GLUT window is available in the global variable <TT>
-glut_window</TT>. </P>
-<P><TT>new Fl_Glut_Window(...)</TT> is the same as <TT>
-glutCreateWindow()</TT> except it does not <TT>show()</TT> the window
+
+The current GLUT window is available in the global variable <tt>
+glut_window</tt>. </P>
+
+<tt>new Fl_Glut_Window(...)</tt> is the same as <tt>
+glutCreateWindow()</tt> except it does not <tt>show()</tt> the window
 or make the window current. </P>
-<P><TT>window->make_current()</TT> is the same as <TT>
-glutSetWindow(number)</TT>.  If the window has not had <TT>show()</TT>
- called on it yet, some functions that assumme an OpenGL context will
-not work.  If you do <TT>show()</TT> the window, call <TT>make_current()</TT>
- again to set the context. </P>
-<P><TT>~Fl_Glut_Window()</TT> is the same as <TT>glutDestroyWindow()</TT>
-. </P>
-<H3>Members</H3>
-The <TT>Fl_Glut_Window</TT> class contains several public members that can
+
+<tt>window->make_current()</tt> is the same as <tt>glutSetWindow(number)</tt>.
+If the window has not had <tt>show()</tt> called on it yet, some functions
+that assumme an OpenGL context will not work. 
+If you do <tt>show()</tt> the window, call <tt>make_current()</tt>
+again to set the context. </P>
+
+<tt>~Fl_Glut_Window()</tt> is the same as <tt>glutDestroyWindow()</tt>.
+
+\subsection glut_members Members
+
+The <tt>Fl_Glut_Window</tt> class contains several public members that can
 be altered directly:
+
 <CENTER><TABLE WIDTH="80%" BORDER="1" ALT="Fl_Glut_Window public members.">
 <TR>
 	<TH>member</TH>
@@ -169,25 +207,33 @@ be altered directly:
 </TR>
 </TABLE></CENTER>
 
-<H3>Methods</H3>
-<UL>
-<LI><A href=#Fl_Glut_Window.Fl_Glut_Window>Fl_Glut_Window</A></LI>
-<LI><A href=#Fl_Glut_Window.~Fl_Glut_Window>~Fl_Glut_Window</A></LI>
-<LI><A href=#Fl_Glut_Window.make_current>make_current</A></LI>
-</UL>
-<H4><A name=Fl_Glut_Window.Fl_Glut_Window>
+\subsection glut_methods Methods
+
+\li <A href=#Fl_Glut_Window.Fl_Glut_Window>Fl_Glut_Window</A>
+\li <A href=#Fl_Glut_Window.~Fl_Glut_Window>~Fl_Glut_Window</A>
+\li <A href=#Fl_Glut_Window.make_current>make_current</A>
+
+<A name="Fl_Glut_Window.Fl_Glut_Window"></A> <!-- For old HTML links only ! -->
 Fl_Glut_Window::Fl_Glut_Window(int x, int y, int w, int h, const char
-*title = 0)
-<BR> Fl_Glut_Window::Fl_Glut_Window(int w, int h, const char *title = 0)</A>
-</H4>
- The first constructor takes 4 int arguments to create the window with
+*title = 0) <br>
+Fl_Glut_Window::Fl_Glut_Window(int w, int h, const char *title = 0)
+
+\par
+The first constructor takes 4 int arguments to create the window with
 a preset position and size.  The second constructor with 2 arguments
 will create the window with a preset size, but the window manager will
 choose the position according to it's own whims.
-<H4><A name=Fl_Glut_Window.~Fl_Glut_Window>virtual
-Fl_Glut_Window::~Fl_Glut_Window()</A></H4>
- Destroys the GLUT window.
-<H4><A name="Fl_Glut_Window.make_current">void Fl_Glut_Window::make_current()</A></H4>
+
+<A name="Fl_Glut_Window.~Fl_Glut_Window"> </A> <!-- For old HTML links only ! -->
+virtual Fl_Glut_Window::~Fl_Glut_Window()
+
+\par
+Destroys the GLUT window.
+
+<A name="Fl_Glut_Window.make_current"> </A> <!-- For old HTML links only ! -->
+void Fl_Glut_Window::make_current()
+
+\par
 Switches all drawing functions to the GLUT window.
 
 <hr>