diff options
Diffstat (limited to 'documentation/basics.html')
| -rw-r--r-- | documentation/basics.html | 391 |
1 files changed, 242 insertions, 149 deletions
diff --git a/documentation/basics.html b/documentation/basics.html index 58ae3fd02..cf2f1eaf9 100644 --- a/documentation/basics.html +++ b/documentation/basics.html @@ -1,70 +1,18 @@ -<HTML><BODY> +<HTML> +<BODY> + <H1 ALIGN=RIGHT><A NAME=basics>2 - FLTK Basics</A></H1> - This chapter will teach you the basics of compiling programs that use -FLTK. -<H2>Naming</H2> - All public symbols in FLTK start with the characters 'F' and 'L': -<UL> -<LI>Functions are either <TT>Fl::foo()</TT> or <TT>fl_foo()</TT>. </LI> -<LI>Class and type names are capitalized: <TT>Fl_Foo</TT>. </LI> -<LI><A href=enumerations.html#Enumerations>Constants and enumerations</A> - are uppercase: <TT>FL_FOO</TT>. </LI> -<LI>All header files start with <TT><FL/...></TT>. </LI> -</UL> -<H2>Header Files</H2> - The proper way to include FLTK header files is: -<UL> -<PRE> -#include <FL/Fl_xyz.H> -</PRE> -</UL> -<B>Microsoft Windows developers please note:</B> case *is* significant -under other operating systems, and the C standard uses the forward -slash (/) to separate directories. <i>Do not do any of the following:</i> -<UL> -<PRE> -#include <FL\Fl_xyz.H> -#include <fl/fl_xyz.h> -#include <Fl/fl_xyz.h> -</PRE> -</UL> -<H2>Compiling Programs with Standard Compilers</H2> - 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: -<UL> -<PRE> -CC -I/usr/local/include ... -gcc -I/usr/local/include ... -</PRE> -</UL> - Similarly, when linking your application you will need to tell the -compiler to use the FLTK library: -<UL> -<PRE> -CC ... -L/usr/local/lib -lfltk -lXext -lX11 -lm -gcc ... -L/usr/local/lib -lfltk -lXext -lX11 -lm -</PRE> -</UL> -<H2>Compiling Programs with Microsoft Visual C++</H2> - 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 WinSock (WSOCK32.LIB) -libraries to the "Link" settings. -<P>You can build your Microsoft Windows applications as Console or -WIN32 applications. If you want to use the standard C <TT>main()</TT> - function as the entry point, FLTK includes a <TT>WinMain()</TT> - function that will call your <TT>main()</TT> function for you. </P> -<P><I>Note: The Visual C++ 5.0 optimizer is known to cause problems with -many programs. We only recommend using the "Favor Small Code" -optimization setting.</I> The Visual C++ 6.0 optimizer seems to be much -better and can be used with the "optimized for speed" setting.</P> + +<P>This chapter teaches you the basics of compiling programs +that use FLTK.</P> + <H2>Writing Your First FLTK Program</H2> - 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. + +<P>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.</P> + <UL> <P><I>Listing 1 - "hello.cxx"</I> <PRE> @@ -83,111 +31,256 @@ int main(int argc, char **argv) { window->show(argc, argv); return Fl::run(); } -</PRE> -</UL> - After including the required header files, the program then creates a -window: -<UL> -<PRE> +</PRE></UL> + +<P>After including the required header files, the program then creates a +window:</P> + +<UL><PRE> Fl_Window *window = new <A href=Fl_Window.html#Fl_Window>Fl_Window</A>(300,180); -</PRE> -</UL> - and a box with the "Hello, World!" string in it: -<UL> -<PRE> +</PRE></UL> + +<P>and a box with the "Hello, World!" string in it:</P> + +<UL><PRE> Fl_Box *box = new <A href=Fl_Box.html#Fl_Box>Fl_Box</A>(20,40,260,100,"Hello, World!"); -</PRE> -</UL> - Next, we set the type of box and the size, font, and style of the label: -<UL> -<PRE> +</PRE></UL> + +<P>Next, we set the type of box and the size, font, and style of the label:</P> + +<UL><PRE> box->box(FL_UP_BOX); box-><A href=Fl_Widget.html#Fl_Widget.labelsize>labelsize</A>(36); box-><A href=Fl_Widget.html#Fl_Widget.labelfont>labelfont</A>(FL_BOLD+FL_ITALIC); box-><A href=Fl_Widget.html#Fl_Widget.labeltype>labeltype</A>(FL_SHADOW_LABEL); -</PRE> -</UL> - Finally, we show the window and enter the FLTK event loop: -<UL> -<PRE> +</PRE></UL> + +<P>Finally, we show the window and enter the FLTK event loop:</P> + +<UL><PRE> window-><A href=Fl_Group.html#Fl_Group.end>end</A>(); window-><A href=Fl_Window.html#Fl_Window.show>show</A>(argc, argv); return <A href=functions.html#run>Fl::run</A>(); -</PRE> -</UL> -The resulting program will display the window below. You can quit the -program by closing the window or pressing the ESCape key. -<P ALIGN=CENTER><IMG src="hello.C.gif" alt="Hello, World! Window"></P> +</PRE></UL> + +<P>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.</P> + +<P ALIGN="CENTER"><IMG src="hello.C.gif" alt="Hello, World! Window"><BR> +<I>Figure 2-1: The Hello, World! Window</I></P> + <H3>Creating the Widgets</H3> - The widgets are created using the C++ <TT>new</TT> operator. For - most widgets the arguments to the constructor are: -<UL> -<PRE> + +<P>The widgets are created using the C++ <TT>new</TT> operator. For +most widgets the arguments to the constructor are:</P> + +<UL><PRE> Fl_Widget(x, y, width, height, label) -</PRE> -</UL> -<P>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. </P> -<P>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. </P> -<p><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. +</PRE></UL> + +<P>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.</P> + +<P>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.</P> + +<P><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.</P> + <H3>Get/Set Methods</H3> -<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#boytypes"> -Chapter 3</A>. -<p>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". + +<P><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#boytypes">Chapter 3</A>.</P> + +<P>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".</P> <H3>Redrawing After Changing Attributes</H3> -<p>Almost all of the set/get pairs are very fast, short inline -functions and thus very efficient. However, <i>the "set" methods do -not call <TT>redraw()</TT></i> - you have to call it yourself. This greatly -reduces code size and execution time. The only common exception is -<tt>value()</tt> which calls <TT>redraw()</TT> if necessary. + +<P>Almost all of the set/get pairs are very fast, short inline +functions and thus very efficient. However, <i>the "set" +methods do not call <TT>redraw()</TT></i> - you have to call it +yourself. This greatly reduces code size and execution time. +The only common exception is <tt>value()</tt> which calls +<TT>redraw()</TT> if necessary.</P> <H3>Labels</H3> -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. -<P>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. </P> -<P>The <TT>labelsize</TT> method sets the height of the font in pixels. </P> -<P>The <TT>labeltype</TT> method sets the type of label. FLTK supports -normal, embossed, shadowed, symbol, and image labels internally, and -more types can be added as desired. </P> -<P>A complete list of all label options can be found in <A href=common.html#labels> -Chapter 3</A>. </P> + +<P>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.</P> + +<P>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. </P> <P>The <TT>labelsize</TT> method sets +the height of the font in pixels. </P> <P>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.</P> + +<P>A complete list of all label options can be found in +<A href="common.html#labels">Chapter 3</A>.</P> <H3>Showing the Window</H3> - The <TT>show()</TT> method shows the widget or window. For windows + +<P>The <TT>show()</TT> method shows the widget or window. For windows you can also provide the command-line arguments to allow users to -customize the appearance, size, and position of your windows. +customize the appearance, size, and position of your windows.</P> + <H3>The Main Event Loop</H3> - FLTK provides the <A href=functions.html#run><TT>Fl:run()</TT></A> - method to enter a standard event processing loop. This is equivalent -to the following code: -<UL> -<PRE> + +<P>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.</P> + +<P>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.</P> + +<P>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.</P> + +<P>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.</P> + +<P>FLTK applications must periodically check +(<TT>Fl::check()</TT>) or wait (<TT>Fl::wait()</TT>) for events +or use the <A href="functions.html#run"><TT>Fl:run()</TT></A> +method to enter a standard event processing loop. Calling +<TT>Fl::run()</TT> is equivalent to the following code:</P> + +<UL><PRE> while (Fl::wait()); -</PRE> +</PRE></UL> + +<P><TT>Fl::run()</TT> does not return until all of the windows +under FLTK control are closed by the user or your program.</P> + +<H2>Compiling Programs with Standard Compilers</H2> + +<P>Under UNIX (and under Microsoft Windows when using the GNU development +tools) you will probably need to tell the compiler where to find the +header files. This is usually done using the <TT>-I</TT> option:</P> + +<UL><PRE> +CC -I/usr/local/include ... +gcc -I/usr/local/include ... +</PRE></UL> + +<P>The <TT>fltk-config</TT> script included with FLTK can be +used to get the options that are required by your compiler:</P> + +<UL><PRE> +CC `fltk-config --cxxflags` ... +</PRE></UL> + +<P>Similarly, when linking your application you will need to tell the +compiler to use the FLTK library:</P> + +<UL><PRE> +CC ... -L/usr/local/lib -lfltk -lXext -lX11 -lm +gcc ... -L/usr/local/lib -lfltk -lXext -lX11 -lm +</PRE></UL> + +<P>The <TT>fltk-config</TT> script included with FLTK can be +used to get the options that are required by your linker:</P> + +<UL><PRE> +CC ... `fltk-config --ldflags` +</PRE></UL> + +<H2>Compiling Programs with Microsoft Visual C++</H2> + +<P>In Visual C++ you will need to tell the compiler where to +find the FLTK header files. This can be done by selecting +"Settings" from the "Project" menu and then +changing the "Preprocessor" settings under the +"C/C++" tab. You will also need to add the FLTK and +WinSock (WSOCK32.LIB) libraries to the "Link" +settings.</P> + +<P>You can build your Microsoft Windows applications as Console or +WIN32 applications. If you want to use the standard C <TT>main()</TT> +function as the entry point, FLTK includes a <TT>WinMain()</TT> +function that will call your <TT>main()</TT> function for you.</P> + +<P><I>Note: The Visual C++ 5.0 optimizer is known to cause problems with +many programs. We only recommend using the "Favor Small Code" +optimization setting.</I> The Visual C++ 6.0 optimizer seems to be much +better and can be used with the "optimized for speed" setting.</P> + +<H2>Naming</H2> + +<P>All public symbols in FLTK start with the characters 'F' and 'L':</P> + +<UL> + + <LI>Functions are either <TT>Fl::foo()</TT> or + <TT>fl_foo()</TT>.</LI> + + <LI>Class and type names are capitalized: + <TT>Fl_Foo</TT>.</LI> + + <LI><A href="enumerations.html">Constants and + enumerations</A> are uppercase: <TT>FL_FOO</TT>.</LI> + + <LI>All header files start with <TT><FL/...></TT>. + </LI> + </UL> -<TT>Fl::run()</TT> does not return until all of the windows under FLTK -control are closed by the user or your program. + +<H2>Header Files</H2> + +<P>The proper way to include FLTK header files is:</P> + +<UL><PRE> +#include <FL/Fl_xyz.H> +</PRE></UL> + +<P><B>Microsoft Windows developers please note:</B> case *is* +significant under other operating systems, and the C standard +uses the forward slash (/) to separate directories. <i>Do not +use any of the following include lines:</i></P> + +<UL><PRE> +#include <FL\Fl_xyz.H> +#include <fl/fl_xyz.h> +#include <Fl/fl_xyz.h> +</PRE></UL> + </BODY> </HTML> |