now renaming restoring dir src_doc src.

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

1 files changed, 352 insertions, 0 deletions

diff --git a/documentation/src/basics.dox b/documentation/src/basics.dox
new file mode 100644
index 000000000..fc177c4ef
--- /dev/null
+++ b/documentation/src/basics.dox
@@ -0,0 +1,352 @@
+/**
+
+ \page basics	2 - FLTK Basics
+ 
+This chapter teaches you the basics of compiling programs
+that use FLTK.
+
+\section basics_writing Writing Your First FLTK Program
+
+All programs must include the file <tt><FL/Fl.H></tt>.
+In addition the program must include a header file for each
+FLTK class it uses. Listing 1 shows a simple "Hello,
+World!" program that uses FLTK to display the window.
+
+\par Listing 1 - "hello.cxx"
+\code
+#include <FL/Fl.H>
+#include <FL/Fl_Window.H>
+#include <FL/Fl_Box.H>
+
+int main(int argc, char **argv) {
+  Fl_Window *window = new Fl_Window(300,180);
+  Fl_Box *box = new Fl_Box(20,40,260,100,"Hello, World!");
+  box->box(FL_UP_BOX);
+  box->labelsize(36);
+  box->labelfont(FL_BOLD+FL_ITALIC);
+  box->labeltype(FL_SHADOW_LABEL);
+  window->end();
+  window->show(argc, argv);
+  return Fl::run();
+}
+\endcode
+
+<!-- NEED 2in -->
+
+After including the required header files, the program then creates a
+window. All following widgets will automatically be children of this window.
+
+\code
+Fl_Window *window = new Fl_Window(300,180);
+\endcode
+
+Then we create a box with the "Hello, World!" string in it. FLTK automatically
+adds the new box to <tt>window</tt>, the current grouping widget.
+
+\code
+Fl_Box *box = new Fl_Box(20,40,260,100,"Hello, World!");
+\endcode
+
+Next, we set the type of box and the size, font, and style of the label:
+
+\code
+box->box(FL_UP_BOX);
+box->labelsize(36);
+box->labelfont(FL_BOLD+FL_ITALIC);
+box->labeltype(FL_SHADOW_LABEL);
+\endcode
+
+We tell FLTK that we will not add any more widgets to <tt>window</tt>.
+
+\code
+window->end();
+\endcode
+
+Finally, we show the window and enter the FLTK event loop:
+
+\code
+window->show(argc, argv);
+return Fl::run();
+\endcode
+
+The resulting program will display the window in Figure 2-1.
+You can quit the program by closing the window or pressing the
+<KBD>ESC</KBD>ape key.
+
+\image html hello.C.gif "Figure 2-1: The Hello, World! Window"
+\image latex hello.C.eps "The Hello, World! Window" width=8cm
+\subsection basics_creating Creating the Widgets
+
+The widgets are created using the C++ <tt>new</tt> operator.  For
+most widgets the arguments to the constructor are:
+
+\code
+Fl_Widget(x, y, width, height, label)
+\endcode
+
+The <tt>x</tt> and <tt>y</tt> parameters determine where the
+widget or window is placed on the screen. In FLTK the top left
+corner of the window or screen is the origin (i.e. x = 0, y =
+0) and the units are in pixels.
+
+The <tt>width</tt> and <tt>height</tt> parameters determine
+the size of the widget or window in pixels. The maximum widget
+size is typically governed by the underlying window system or
+hardware.
+
+<tt>label</tt> is a pointer to a character string to label
+the widget with or <tt>NULL</tt>. If not specified the label
+defaults to <tt>NULL</tt>. The label string must be in static
+storage such as a string constant because FLTK does not make a
+copy of it - it just uses the pointer.
+
+\subsection basics_hierarchies Creating Widget hierarchies
+
+Widgets are commonly ordered into functional groups, which 
+in turn may be grouped again, creating a hierarchy of widgets. 
+FLTK makes it easy to fill groups by automatically adding all widgets 
+that are created between a <tt>myGroup->begin()</tt> and 
+<tt>myGroup->end()</tt>. In this example, <tt>myGroup</tt>  
+would be the <i>current</i> group.
+
+Newly created groups and their derived widgets implicitly call
+<tt>begin()</tt> in the constructor, effectively adding all 
+subsequently created widgets to itself until <tt>end()</tt> 
+is called.
+
+Setting the current group to <tt>NULL</tt> will stop automatic
+hierarchies. New widgets can now be added manually using 
+<tt>Fl_Group::add(...)</tt> and <tt>Fl_Group::insert(...)</tt>.
+
+\subsection basics_getset Get/Set Methods
+
+<tt>box->box(FL_UP_BOX)</tt> sets the type of box the
+Fl_Box draws, changing it from the default of
+<tt>FL_NO_BOX</tt>, which means  that no box is drawn. In our
+"Hello, World!" example we use <tt>FL_UP_BOX</tt>,
+which means that a raised button border will be drawn around
+the widget. You can learn more about boxtypes in
+<A href="common.html#boxtypes">Chapter 3</A>.
+
+You could examine the boxtype in by doing
+<tt>box->box()</tt>. FLTK uses method name overloading to make
+short names for get/set methods. A "set" method is always of
+the form "void name(type)", and a "get" method is always
+of the form "type name() const".
+
+\subsection basics_redrawing Redrawing After Changing Attributes
+
+Almost all of the set/get pairs are very fast, short inline
+functions and thus very efficient. However, <i>the "set" methods
+do not call <tt>redraw()</tt></i> - you have to call it
+yourself. This greatly reduces code size and execution time. The
+only common exceptions are <tt>value()</tt> which calls
+<tt>redraw()</tt> and <tt>label()</tt> which calls
+<tt>redraw_label()</tt> if necessary.
+
+\subsection basics_labels Labels
+
+All widgets support labels.  In the case of window widgets,
+the label is used for the label in the title bar. Our example
+program calls the <tt>labelfont()</tt>,<tt> labelsize</tt>,
+and <tt>labeltype()</tt> methods.
+
+All widgets support labels.  In the case of window widgets,
+the label  is used for the label in the title bar. Our example
+program calls the
+<A href=Fl_Widget.html#Fl_Widget.labelfont><tt>labelfont</tt></A>,
+<A href=Fl_Widget.html#Fl_Widget.labelsize><tt> labelsize</tt></A>,
+and
+<A href=Fl_Widget.html#Fl_Widget.labeltype><tt>labeltype</tt></A>
+methods.
+
+The <tt>labelfont</tt> method sets the typeface and style
+that is used for the label, which for this example we are using
+<tt>FL_BOLD</tt> and <tt>FL_ITALIC</tt>. You can also specify
+typefaces directly.
+
+The <tt>labelsize</tt> method sets the height of the font in pixels.
+
+The <tt>labeltype</tt>
+method sets the type of label. FLTK supports normal, embossed,
+and shadowed labels internally, and more types can be added as
+desired.
+
+A complete list of all label options can be found in
+<A href="common.html#labels">Chapter 3</A>.
+
+\subsection basics_showing Showing the Window
+
+The <tt>show()</tt> method shows the widget or window. For windows
+you can also provide the command-line arguments to allow users to
+customize the appearance, size, and position of your windows.
+
+\subsection basics_eventloop The Main Event Loop
+
+All FLTK applications (and most GUI applications in general)
+are based on a simple event processing model. User actions such
+as mouse movement, button clicks, and keyboard activity generate
+events that are sent to an application. The application may then
+ignore the events or respond to the user, typically by redrawing
+a button in the "down" position, adding the text to an input
+field, and so forth.
+
+FLTK also supports idle, timer, and file pseudo-events that
+cause a function to be called when they occur. Idle functions
+are called when no user input is present and no timers or files
+need to be handled - in short, when the application is not doing
+anything. Idle callbacks are often used to update a 3D display
+or do other background processing.
+
+Timer functions are called after a specific amount of time
+has expired. They can be used to pop up a progress dialog after
+a certain amount of time or do other things that need to happen
+at more-or-less regular intervals. FLTK timers are not 100%
+accurate, so they should not be used to measure time intervals,
+for example.
+
+File functions are called when data is ready to read or
+write, or when an error condition occurs on a file. They are
+most often used to monitor network connections (sockets) for
+data-driven displays.
+
+FLTK applications must periodically check (Fl::check()) 
+or wait (Fl::wait()) for events or use the Fl::run()
+method to enter a standard event processing loop. Calling
+Fl::run() is equivalent to the following code:
+
+\code
+while (Fl::wait());
+\endcode
+
+Fl::run() does not return until all of the windows
+under FLTK control are closed by the user or your program.
+
+\section basics_standard_compiler Compiling Programs with Standard Compilers
+
+Under UNIX (and under Microsoft Windows when using the GNU development
+tools) you will probably need to tell the compiler where to find the
+header files. This is usually done using the <tt>-I</tt> option:
+
+\code
+CC -I/usr/local/include ...
+gcc -I/usr/local/include ...
+\endcode
+
+The <tt>fltk-config</tt> script included with FLTK can be
+used to get the options that are required by your compiler:
+
+\code
+CC `fltk-config --cxxflags` ...
+\endcode
+
+Similarly, when linking your application you will need to tell the
+compiler to use the FLTK library:
+
+\code
+CC  ... -L/usr/local/lib -lfltk -lXext -lX11 -lm
+gcc ... -L/usr/local/lib -lfltk -lXext -lX11 -lm
+\endcode
+
+Aside from the "fltk" library, there is also a "fltk_forms"
+library for the XForms compatibility classes, "fltk_gl" for the
+OpenGL and GLUT classes, and "fltk_images" for the image file
+classes, Fl_Help_Dialog widget, and system icon support.
+
+\note
+The libraries are named "fltk.lib", "fltkgl.lib", "fltkforms.lib",
+and "fltkimages.lib", respectively under Windows.
+
+As before, the <tt>fltk-config</tt> script included with FLTK can be
+used to get the options that are required by your linker:
+
+\code
+CC ... `fltk-config --ldflags`
+\endcode
+
+<!-- NEED 2in -->
+
+The forms, GL, and images libraries are included with the "--use-foo"
+options, as follows:
+
+\code
+CC ... `fltk-config --use-forms --ldflags`
+CC ... `fltk-config --use-gl --ldflags`
+CC ... `fltk-config --use-images --ldflags`
+CC ... `fltk-config --use-forms --use-gl --use-images --ldflags`
+\endcode
+
+Finally, you can use the <tt>fltk-config</tt> script to
+compile a single source file as a FLTK program:
+
+\code
+fltk-config --compile filename.cpp
+fltk-config --use-forms --compile filename.cpp
+fltk-config --use-gl --compile filename.cpp
+fltk-config --use-images --compile filename.cpp
+fltk-config --use-forms --use-gl --use-images --compile filename.cpp
+\endcode
+
+Any of these will create an executable named <tt>filename</tt>.
+
+\section basics_visual_cpp Compiling Programs with Microsoft Visual C++
+
+In Visual C++ you will need to tell the compiler where to
+find the  FLTK header files.  This can be done by selecting
+"Settings" from the "Project" menu and then changing the 
+"Preprocessor" settings under the "C/C++" tab. You will also 
+need to add the FLTK and WinSock2 (WS2_32.LIB) libraries to 
+the "Link" settings.
+
+You can build your Microsoft Windows applications as Console or
+WIN32 applications.  If you want to use the standard C <tt>main()</tt>
+function as the entry point, FLTK includes a <tt>WinMain()</tt>
+function that will call your <tt>main()</tt> function for you.
+
+<I>Note: The Visual C++ 5.0 optimizer is known to cause problems with
+many programs. We only recommend using the "Favor Small Code"
+optimization setting.</I> The Visual C++ 6.0 optimizer seems to be much
+better and can be used with the "optimized for speed" setting.
+
+\section basics_naming Naming
+
+All public symbols in FLTK start with the characters 'F' and 'L':
+
+\li Functions are either <tt>Fl::foo()</tt> or <tt>fl_foo()</tt>.
+
+\li Class and type names are capitalized: <tt>Fl_Foo</tt>.
+
+\li <A href="enumerations.html">Constants and enumerations</A>
+    are uppercase: <tt>FL_FOO</tt>.
+
+\li All header files start with <tt><FL/...></tt>.
+
+<!-- NEED 5in -->
+
+\section basics_headerfiles Header Files
+
+The proper way to include FLTK header files is:
+
+\code
+#include <FL/Fl_xyz.H>
+\endcode
+
+\note
+Case <I>is</I> significant on many operating systems,
+and the C standard uses the forward slash (/) to
+separate directories. <i>Do not use any of the following
+include lines:</i>
+
+\code
+#include <FL\Fl_xyz.H>
+#include <fl/fl_xyz.h>
+#include <Fl/fl_xyz.h>
+\endcode
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="intro.html">[Previous]&nbsp; 1 - Introduction to FLTK</a>&nbsp;
+<a class="el" href="common.html">[Next]&nbsp; 3 - Common Widgets and Attributes</a>&nbsp;
+\endhtmlonly
+*/