diff options
| author | Matthias Melcher <fltk@matthiasm.com> | 2011-01-08 16:31:55 +0000 |
|---|---|---|
| committer | Matthias Melcher <fltk@matthiasm.com> | 2011-01-08 16:31:55 +0000 |
| commit | 0b6b69caaa4de4cd3bf5a2e2ebb1a94b1132e823 (patch) | |
| tree | 4846fe3e800834b33783921688014c7b9cd2ee69 /branch-3.0-2011/documentation/src | |
| parent | 2dc664935d8109767c2d107c6b644082fe06ac05 (diff) | |
Accidentaly copied here
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@8219 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
Diffstat (limited to 'branch-3.0-2011/documentation/src')
100 files changed, 0 insertions, 11553 deletions
diff --git a/branch-3.0-2011/documentation/src/FL.png b/branch-3.0-2011/documentation/src/FL.png Binary files differdeleted file mode 100644 index a723eef7d..000000000 --- a/branch-3.0-2011/documentation/src/FL.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/FL200.png b/branch-3.0-2011/documentation/src/FL200.png Binary files differdeleted file mode 100644 index b227fc794..000000000 --- a/branch-3.0-2011/documentation/src/FL200.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/Fl_Check_Button.png b/branch-3.0-2011/documentation/src/Fl_Check_Button.png Binary files differdeleted file mode 100644 index 63cfc8558..000000000 --- a/branch-3.0-2011/documentation/src/Fl_Check_Button.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/Fl_File_Chooser.jpg b/branch-3.0-2011/documentation/src/Fl_File_Chooser.jpg Binary files differdeleted file mode 100644 index 050227d58..000000000 --- a/branch-3.0-2011/documentation/src/Fl_File_Chooser.jpg +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/Fl_File_Input.png b/branch-3.0-2011/documentation/src/Fl_File_Input.png Binary files differdeleted file mode 100644 index 08ce0350d..000000000 --- a/branch-3.0-2011/documentation/src/Fl_File_Input.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/Fl_Help_Dialog.png b/branch-3.0-2011/documentation/src/Fl_Help_Dialog.png Binary files differdeleted file mode 100644 index 11a4b29f5..000000000 --- a/branch-3.0-2011/documentation/src/Fl_Help_Dialog.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/Fl_Light_Button.png b/branch-3.0-2011/documentation/src/Fl_Light_Button.png Binary files differdeleted file mode 100644 index 6eca7d8c2..000000000 --- a/branch-3.0-2011/documentation/src/Fl_Light_Button.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/Fl_Native_File_Chooser.png b/branch-3.0-2011/documentation/src/Fl_Native_File_Chooser.png Binary files differdeleted file mode 100644 index 1f1e6686f..000000000 --- a/branch-3.0-2011/documentation/src/Fl_Native_File_Chooser.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/Fl_Return_Button.png b/branch-3.0-2011/documentation/src/Fl_Return_Button.png Binary files differdeleted file mode 100644 index e8e5d0bf6..000000000 --- a/branch-3.0-2011/documentation/src/Fl_Return_Button.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/Fl_Roller.png b/branch-3.0-2011/documentation/src/Fl_Roller.png Binary files differdeleted file mode 100644 index b85d4746f..000000000 --- a/branch-3.0-2011/documentation/src/Fl_Roller.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/Fl_Round_Button.png b/branch-3.0-2011/documentation/src/Fl_Round_Button.png Binary files differdeleted file mode 100644 index 723c8d549..000000000 --- a/branch-3.0-2011/documentation/src/Fl_Round_Button.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/Fl_Scroll.png b/branch-3.0-2011/documentation/src/Fl_Scroll.png Binary files differdeleted file mode 100644 index 21e3572df..000000000 --- a/branch-3.0-2011/documentation/src/Fl_Scroll.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/Fl_Tile.png b/branch-3.0-2011/documentation/src/Fl_Tile.png Binary files differdeleted file mode 100644 index eafa59c99..000000000 --- a/branch-3.0-2011/documentation/src/Fl_Tile.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/Fl_Value_Input.png b/branch-3.0-2011/documentation/src/Fl_Value_Input.png Binary files differdeleted file mode 100644 index f555c7059..000000000 --- a/branch-3.0-2011/documentation/src/Fl_Value_Input.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/Fl_Value_Output.png b/branch-3.0-2011/documentation/src/Fl_Value_Output.png Binary files differdeleted file mode 100644 index af2f362d0..000000000 --- a/branch-3.0-2011/documentation/src/Fl_Value_Output.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/adjuster1.png b/branch-3.0-2011/documentation/src/adjuster1.png Binary files differdeleted file mode 100644 index 5fb9911f4..000000000 --- a/branch-3.0-2011/documentation/src/adjuster1.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/advanced.dox b/branch-3.0-2011/documentation/src/advanced.dox deleted file mode 100644 index 2d8012a1a..000000000 --- a/branch-3.0-2011/documentation/src/advanced.dox +++ /dev/null @@ -1,129 +0,0 @@ -/** - - \page advanced Advanced FLTK - -This chapter explains advanced programming and design topics -that will help you to get the most out of FLTK. - -\section advanced_multithreading Multithreading - -FLTK supports multithreaded applications using a locking mechanism -based on "pthreads". We do not provide a threading interface as part of -the library. However a simple example how threads can be implemented -for all supported platforms can be found in \p test/threads.h -and \p test/threads.cxx. - -To use the locking mechanism, FLTK must be compiled with -\p --enable-threads set during the \p configure -process. IDE-based versions of FLTK are automatically compiled with -locking enabled if possible. - -In \p main(), call -Fl::lock() before -Fl::run() or -Fl::wait() to start the runtime -multithreading support for your program. All callbacks and derived -functions like \p handle() and \p draw() will now be properly -locked: - -\code - int main() { - Fl::lock(); - /* run thread */ - while (Fl::wait() > 0) { - if (Fl::thread_message()) { - /* process your data */ - } - } - } -\endcode - -You can now start as many threads as you like. From within -a thread (other than the main thread) FLTK calls must be wrapped -with calls to Fl::lock() and Fl::unlock(): - -\code - Fl::lock(); // avoid conflicting calls - ... // your code here - Fl::unlock(); // allow other threads to access FLTK again -\endcode - -You can send messages from child threads to the main thread -using Fl::awake(void* message): - -\code - void *msg; // "msg" is a pointer to your message - Fl::awake(msg); // send "msg" to main thread -\endcode - -A message can be anything you like. The main thread can retrieve -the message by calling Fl::thread_message(). See example above. - -You can also tell the main thread to call a function for you -as soon as possible by using -Fl::awake(Fl_Awake_Handler cb, void* userdata): - -\code - void do_something(void *userdata) { - // running with the main thread - } - - // running in another thread - void *data; // "data" is a pointer to your user data - Fl::awake(do_something, data); // call something in main thread -\endcode - - -FLTK supports multiple platforms, some of which allow only the -main thread to handle system events and open or close windows. -The safe thing to do is to adhere to the following rules for -threads on all operating systems: - - -\li Don't \p show() or \p hide() anything that contains - widgets derived from Fl_Window, including dialogs, file - choosers, subwindows or those using Fl_Gl_Window. - -\li Don't call Fl::wait(), Fl::flush() or any - related methods that will handle system messages - -\li Don't start or cancel timers - -\li Don't change window decorations or titles - -\li The \p make_current() method may or may not work well for - regular windows, but should always work for a Fl_Gl_Window - to allow for high speed rendering on graphics cards with multiple - pipelines - -See also: -Fl::awake(void* message), -Fl::lock(), -Fl::thread_message(), -Fl::unlock(). - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="fluid.html"> - [Prev] - Programming with FLUID - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="unicode.html"> - Unicode and utf-8 Support - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/basics.dox b/branch-3.0-2011/documentation/src/basics.dox deleted file mode 100644 index 4eb268504..000000000 --- a/branch-3.0-2011/documentation/src/basics.dox +++ /dev/null @@ -1,404 +0,0 @@ -/** - - \page basics 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(340,180); - Fl_Box *box = new Fl_Box(20,40,300,100,"Hello, World!"); - box->box(FL_UP_BOX); - box->labelfont(FL_BOLD+FL_ITALIC); - box->labelsize(36); - 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(340,180); -\endcode - -Then we create a box with the "Hello, World!" string in it. FLTK automatically -adds the new box to \p window, the current grouping widget. - -\code -Fl_Box *box = new Fl_Box(20,40,300,100,"Hello, World!"); -\endcode - -Next, we set the type of box and the font, size, and style of the label: - -\code -box->box(FL_UP_BOX); -box->labelfont(FL_BOLD+FL_ITALIC); -box->labelsize(36); -box->labeltype(FL_SHADOW_LABEL); -\endcode - -We tell FLTK that we will not add any more widgets to \p window. - -\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 -<tt>ESC</tt>ape key. - -\image html hello.C.png "Figure 2-1: The Hello, World! Window" -\image latex hello.C.png "The Hello, World! Window" width=8cm - -\subsection basics_creating Creating the Widgets - -The widgets are created using the C++ \p new operator. For -most widgets the arguments to the constructor are: - -\code -Fl_Widget(x, y, width, height, label) -\endcode - -The \p x and \p y 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. <tt>x = 0, y = 0</tt>) -and the units are in pixels. - -The \p width and \p height 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 label is a pointer to a character string to label -the widget with or \p NULL. If not specified the label -defaults to \p NULL. 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, \p myGroup would be the \e current group. - -Newly created groups and their derived widgets implicitly call -\p begin() in the constructor, effectively adding all -subsequently created widgets to itself until \p end() -is called. - -Setting the current group to \p NULL 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 -\p FL_NO_BOX, which means that no box is drawn. In our -"Hello, World!" example we use \p FL_UP_BOX, -which means that a raised button border will be drawn around -the widget. More details are available in the -\ref common_boxtypes -section. - -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 \p redraw()</i> - you have to call it -yourself. This greatly reduces code size and execution time. The -only common exceptions are \p value() which calls -\p redraw() and \p label() which calls -\p redraw_label() 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 \p labelfont(), \p labelsize(), -and \p labeltype() methods. - -The \p labelfont() method sets the typeface and style -that is used for the label, which for this example we are using -\p FL_BOLD and \p FL_ITALIC. You can also specify -typefaces directly. - -The \p labelsize() method sets the height of the font in pixels. - -The \p labeltype() -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 the section on -\ref common_labels. - -\subsection basics_showing Showing the Window - -The \p show() 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 \p -I option: - -\code -CC -I/usr/local/include ... -gcc -I/usr/local/include ... -\endcode - -The \p fltk-config 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 \p fltk-config 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 \p fltk-config 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 \p filename. - -\section basics_makefile Compiling Programs with Makefiles - -The previous section described how to use \p fltk-config to -build a program consisting of a single source file from the command -line, and this is very convenient for small test programs. -But \p fltk-config can also be used to set the compiler and -linker options as variables within a \p Makefile that can be -used to build programs out of multiple source files: - -\code -CXX = $(shell fltk-config --cxx) -DEBUG = -g -CXXFLAGS = $(shell fltk-config --use-gl --use-images --cxxflags ) -I. -LDFLAGS = $(shell fltk-config --use-gl --use-images --ldflags ) -LDSTATIC = $(shell fltk-config --use-gl --use-images --ldstaticflags ) -LINK = $(CXX) - -TARGET = cube -OBJS = CubeMain.o CubeView.o CubeViewUI.o -SRCS = CubeMain.cxx CubeView.cxx CubeViewUI.cxx - -.SUFFIXES: .o .cxx -%.o: %.cxx - $(CXX) $(CXXFLAGS) $(DEBUG) -c $< - -all: $(TARGET) - $(LINK) -o $(TARGET) $(OBJS) $(LDSTATIC) - -$(TARGET): $(OBJS) -CubeMain.o: CubeMain.cxx CubeViewUI.h -CubeView.o: CubeView.cxx CubeView.h CubeViewUI.h -CubeViewUI.o: CubeViewUI.cxx CubeView.h - -clean: $(TARGET) $(OBJS) - rm -f *.o 2> /dev/null - rm -f $(TARGET) 2> /dev/null -\endcode - -\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 (<tt>FLTK.LIB</tt> or <tt>FLTKD.LIB</tt>) and the Windows -Common Controls (<tt>COMCTL32.LIB</tt>) libraries to the "Link" settings. -You must also define <tt>WIN32</tt>. - -More information can be found in <tt>README.MSWindows.txt</tt>. - -You can build your Microsoft Windows applications as Console or -Desktop applications. If you want to use the standard C \p main() -function as the entry point, FLTK includes a \p WinMain() -function that will call your \p main() function for you. - -\section basics_naming Naming - -All public symbols in FLTK start with the characters 'F' and 'L': - -\li Functions are either \p Fl::foo() or \p fl_foo(). - -\li Class and type names are capitalized: \p Fl_Foo. - -\li \ref enumerations "Constants and enumerations" - are uppercase: \p FL_FOO. - -\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 \e is 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> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="intro.html"> - [Prev] - Introduction to FLTK - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="common.html"> - Common Widgets and Attributes - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/blocks.man b/branch-3.0-2011/documentation/src/blocks.man deleted file mode 100644 index 920300708..000000000 --- a/branch-3.0-2011/documentation/src/blocks.man +++ /dev/null @@ -1,26 +0,0 @@ -.TH blocks 6 "FLTK Checkers" "15 January 2006" -.SH NAME -blocks \- the fltk block attack! game -.sp -.SH SYNOPSIS -\fIBlocks\fR is a FLTK-based block elimination game. Stacks of -colored blocks move from right to left as you try to eliminate -groups adjacent blocks by clicking on them. As the game -progresses, more colors are added (up to a maximum of 7) and the -blocks move faster and faster. -.SH GAME PLAY -Press the N key to start a game. As the blocks move across the -window, click on groups of two or more blocks to clear them - the -larger the number of adjacent blocks, the greater the score. -Clicking on a blocks containing a dark ball will clear all blocks -of that color, however you will score much fewer points than a -normal click. The game is over when the blocks reach the left -side of the window. -.LP -Press the spacebar to pause the game. -.SH SEE ALSO -fltk(3) -.br -FLTK Web Site, http://www.fltk.org/ -.SH AUTHOR -Michael R Sweet. diff --git a/branch-3.0-2011/documentation/src/boxtypes.png b/branch-3.0-2011/documentation/src/boxtypes.png Binary files differdeleted file mode 100644 index a64ccaaee..000000000 --- a/branch-3.0-2011/documentation/src/boxtypes.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/buttons.png b/branch-3.0-2011/documentation/src/buttons.png Binary files differdeleted file mode 100644 index 66fd2b033..000000000 --- a/branch-3.0-2011/documentation/src/buttons.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/charts.png b/branch-3.0-2011/documentation/src/charts.png Binary files differdeleted file mode 100644 index 9771bd266..000000000 --- a/branch-3.0-2011/documentation/src/charts.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/checkers.man b/branch-3.0-2011/documentation/src/checkers.man deleted file mode 100644 index 097277474..000000000 --- a/branch-3.0-2011/documentation/src/checkers.man +++ /dev/null @@ -1,24 +0,0 @@ -.TH checkers 6 "FLTK Checkers" "15 January 2006" -.SH NAME -checkers \- the fltk checkers game -.sp -.SH SYNOPSIS -\fICheckers\fR is a FLTK-based version of the game of checkers. -The game is played on an 8x8 board with each player starting with -12 pieces or "checkers" on opposite sides of the board. The -computer plays the white checkers in this version of the game. -.LP -The object of the game is to remove all of your opponents pieces. -Players move one of their pieces diagonally forward on each move, -either a single space or by "jumping" an adjacent piece. Your -opponents pieces are removed by jumping them - you can make -multiple jumps in a single turn. -.LP -If a piece reaches the other side of the board, it is converted -to a "king" which can move both forwards and backwards. -.SH SEE ALSO -fltk(3) -.br -FLTK Web Site, http://www.fltk.org/ -.SH AUTHORS -Bill Spitzak and others. diff --git a/branch-3.0-2011/documentation/src/choice.png b/branch-3.0-2011/documentation/src/choice.png Binary files differdeleted file mode 100644 index 614002c72..000000000 --- a/branch-3.0-2011/documentation/src/choice.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/clock.png b/branch-3.0-2011/documentation/src/clock.png Binary files differdeleted file mode 100644 index 4a845d88c..000000000 --- a/branch-3.0-2011/documentation/src/clock.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/common.dox b/branch-3.0-2011/documentation/src/common.dox deleted file mode 100644 index 1ab29dfab..000000000 --- a/branch-3.0-2011/documentation/src/common.dox +++ /dev/null @@ -1,645 +0,0 @@ -/** - - \page common Common Widgets and Attributes - -This chapter describes many of the widgets that are provided -with FLTK and covers how to query and set the standard -attributes. - -\section common_buttons Buttons - -FLTK provides many types of buttons: - -\li Fl_Button - A standard push button. - -\li Fl_Check_Button - A button with a check box. - -\li Fl_Light_Button - A push button with a light. - -\li Fl_Repeat_Button - A push button that repeats when held. - -\li Fl_Return_Button - A push button that is activated by the - \p Enter key. - -\li Fl_Round_Button - A button with a radio circle. - -\image html buttons.png "Figure 3-1: FLTK Button Widgets" -\image latex buttons.png "FLTK Button Widgets" width=10cm - -All of these buttons just need the corresponding -<tt><FL/Fl_xyz_Button.H></tt> header file. The constructor -takes the bounding box of the button and optionally a label -string: - -\code -Fl_Button *button = new Fl_Button(x, y, width, height, "label"); -Fl_Light_Button *lbutton = new Fl_Light_Button(x, y, width, height); -Fl_Round_Button *rbutton = new Fl_Round_Button(x, y, width, height, "label"); -\endcode - -Each button has an associated \p type() which allows -it to behave as a push button, toggle button, or radio button: - -\code -button->type(FL_NORMAL_BUTTON); -lbutton->type(FL_TOGGLE_BUTTON); -rbutton->type(FL_RADIO_BUTTON); -\endcode - -For toggle and radio buttons, the \p value() method returns -the current button state (0 = off, 1 = on). The \p set() and -\p clear() methods can be used on toggle buttons to turn a -toggle button on or off, respectively. -Radio buttons can be turned on with the \p setonly() -method; this will also turn off other radio buttons in the same -group. - -\section common_text Text - -FLTK provides several text widgets for displaying and receiving text: - -\li Fl_Input - A one-line text input field. - -\li Fl_Output - A one-line text output field. - -\li Fl_Multiline_Input - A multi-line text input field. - -\li Fl_Multiline_Output - A multi-line text output field. - -\li Fl_Text_Display - A multi-line text display widget. - -\li Fl_Text_Editor - A multi-line text editing widget. - -\li Fl_Help_View - A HTML text display widget. - -The Fl_Output and Fl_Multiline_Output -widgets allow the user to copy text from the output field but -not change it. - -The \p value() method is used to get or set the -string that is displayed: - -\code -Fl_Input *input = new Fl_Input(x, y, width, height, "label"); -input->value("Now is the time for all good men..."); -\endcode - -The string is copied to the widget's own storage when you set -the \p value() of the widget. - -The Fl_Text_Display and Fl_Text_Editor -widgets use an associated Fl_Text_Buffer class for the -value, instead of a simple string. - -<!-- NEED 4in --> - -\section common_valuators Valuators - -Unlike text widgets, valuators keep track of numbers instead of -strings. FLTK provides the following valuators: - -\li Fl_Counter - A widget with arrow buttons that shows the current value. - -\li Fl_Dial - A round knob. - -\li Fl_Roller - An SGI-like dolly widget. - -\li Fl_Scrollbar - A standard scrollbar widget. - -\li Fl_Slider - A scrollbar with a knob. - -\li Fl_Value_Slider - A slider that shows the current value. - -\image html valuators.png "Figure 3-2: FLTK valuator widgets" -\image latex valuators.png "FLTK valuator widgets" width=10cm - -The \p value() method gets and sets the current value -of the widget. The \p minimum() and \p maximum() -methods set the range of values that are reported by the -widget. - -<!-- NEED 5in --> - -\section common_groups Groups - -The Fl_Group widget class is used as a general -purpose "container" widget. Besides grouping radio -buttons, the groups are used to encapsulate windows, tabs, and -scrolled windows. The following group classes are available -with FLTK: - -\li Fl_Double_Window - A double-buffered window on the screen. - -\li Fl_Gl_Window - An OpenGL window on the screen. - -\li Fl_Group - The base container class; can be used to group - any widgets together. - -\li Fl_Pack - A collection of widgets that are packed into the group area. - -\li Fl_Scroll - A scrolled window area. - -\li Fl_Tabs - Displays child widgets as tabs. - -\li Fl_Tile - A tiled window area. - -\li Fl_Window - A window on the screen. - -\li Fl_Wizard - Displays one group of widgets at a time. - -\section common_sizeposition Setting the Size and Position of Widgets - -The size and position of widgets is usually set when you create them. -You can access them with the \p x(), \p y(), \p w(), and \p h() -methods. - -You can change the size and position by using the \p position(), -\p resize(), and \p size() methods: - -\code -button->position(x, y); -group->resize(x, y, width, height); -window->size(width, height); -\endcode - -If you change a widget's size or position after it is -displayed you will have to call \p redraw() on the -widget's parent. - -\section common_colors Colors - -FLTK stores the colors of widgets as an 32-bit unsigned -number that is either an index into a color palette of 256 -colors or a 24-bit RGB color. The color palette is \e not -the X or MS Windows colormap, but instead is an internal table with -fixed contents. - -See the -\ref drawing_colors -section of -\ref drawing -for implementation details. - -There are symbols for naming some of the more common colors: - -\li \p FL_BLACK -\li \p FL_RED -\li \p FL_GREEN -\li \p FL_YELLOW -\li \p FL_BLUE -\li \p FL_MAGENTA -\li \p FL_CYAN -\li \p FL_WHITE -\li \p FL_WHITE - -Other symbols are used as the default colors for all FLTK widgets. - -\li \p FL_FOREGROUND_COLOR -\li \p FL_BACKGROUND_COLOR -\li \p FL_INACTIVE_COLOR -\li \p FL_SELECTION_COLOR - -The full list of named color values can be found in -\ref enumerations_colors "FLTK Enumerations". - -A color value can be created from its RGB components by using the -\p %fl_rgb_color() function, and decomposed again with -\p Fl::get_color(): - -\code -Fl_Color c = fl_rgb_color(85, 170, 255); // RGB to Fl_Color -Fl::get_color(c, r, g, b); // Fl_Color to RGB -\endcode - -The widget color is set using the \p color() method: - -\code -button->color(FL_RED); // set color using named value -\endcode - -Similarly, the label color is set using the \p labelcolor() method: - -\code -button->labelcolor(FL_WHITE); -\endcode - -The Fl_Color encoding maps to a 32-bit unsigned integer representing -RGBI, so it is also possible to specify a color using a hex constant -as a color map index: - -\code -button->color(0x000000ff); // colormap index #255 (FL_WHITE) -\endcode - -or specify a color using a hex constant for the RGB components: - -\code -button->color(0xff000000); // RGB: red -button->color(0x00ff0000); // RGB: green -button->color(0x0000ff00); // RGB: blue -button->color(0xffffff00); // RGB: white -\endcode - -\note -If TrueColor is not available, any RGB colors will be set to -the nearest entry in the colormap. - -\section common_boxtypes Box Types - -The type Fl_Boxtype stored and returned in Fl_Widget::box() -is an enumeration defined in Enumerations.H. - -Figure 3-3 shows the standard box types included with FLTK. - -\image html boxtypes.png "Figure 3-3: FLTK box types" -\image latex boxtypes.png "FLTK box types" width=12cm - -\p FL_NO_BOX means nothing is drawn at all, so whatever is -already on the screen remains. The <tt>FL_..._FRAME</tt> types only -draw their edges, leaving the interior unchanged. The blue color in -Figure 3-3 is the area that is not drawn by the frame types. - -\subsection common_custom_boxtypes Making Your Own Boxtypes - -You can define your own boxtypes by making a small function that draws -the box and adding it to the table of boxtypes. - -<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> -<TR> - <TD><B>Note:</B> - <P>This interface has changed in FLTK 2.0! - </TD> -</TR> -</TABLE></CENTER> - -\par The Drawing Function - -The drawing function is passed the bounding box and background color -for the widget: - -\code -void xyz_draw(int x, int y, int w, int h, Fl_Color c) { -... -} -\endcode - -<!-- NEED 3in --> - -A simple drawing function might fill a rectangle with the -given color and then draw a black outline: - -\code -void xyz_draw(int x, int y, int w, int h, Fl_Color c) { - fl_color(c); - fl_rectf(x, y, w, h); - fl_color(FL_BLACK); - fl_rect(x, y, w, h); -} -\endcode - -\anchor common_fl_down -Fl_Boxtype fl_down(Fl_Boxtype b) - -\par -fl_down() returns the "pressed" or "down" version of a box. -If no "down" version of a given box exists, the behavior of this function -is undefined and some random box or frame is returned. -See \ref drawing_fl_frame "Drawing Functions" for more details. - -\anchor common_fl_frame -Fl_Boxtype fl_frame(Fl_Boxtype b) - -\par -fl_frame() returns the unfilled, frame-only version of a box. -If no frame version of a given box exists, the behavior of this function -is undefined and some random box or frame is returned. -See \ref drawing_fl_frame "Drawing Functions" for more details. - -Fl_Boxtype fl_box(Fl_Boxtype b) - -\par -fl_box() returns the filled version of a frame. -If no filled version of a given frame exists, the behavior of this function -is undefined and some random box or frame is returned. -See \ref drawing_fl_frame "Drawing Functions" for more details. - -\par Adding Your Box Type - -The Fl::set_boxtype() method adds or replaces the specified box type: - -\code -#define XYZ_BOX FL_FREE_BOXTYPE - -Fl::set_boxtype(XYZ_BOX, xyz_draw, 1, 1, 2, 2); -\endcode -The last 4 arguments to Fl::set_boxtype() are the -offsets for the \p x, \p y, \p width, and \p height values that should be -subtracted when drawing the label inside the box. - -A complete box design contains four box types in this order: -a filled, neutral box (<tt>UP_BOX</tt>), -a filled, depressed box (<tt>DOWN_BOX</tt>), -and the same as outlines only (<tt>UP_FRAME</tt> and <tt>DOWN_FRAME</tt>). -The function -\ref common_fl_down "fl_down(Fl_Boxtype)" -expects the neutral design on a boxtype with a numerical -value evenly dividable by two. -\ref common_fl_frame "fl_frame(Fl_Boxtype)" -expects the \p UP_BOX design at a value dividable by four. - -\section common_labels Labels and Label Types - -The \p label(), \p align(), \p labelfont(), \p labelsize(), -\p labeltype(), \p image(), and \p deimage() methods control the -labeling of widgets. - -\par label() - -The \p label() method sets the string that is displayed -for the label. Symbols can be included with the label string by -escaping them using the "@" symbol - "@@" displays a single at -sign. Figure 3-4 shows the available symbols. - -\image html symbols.png "Figure 3-4: FLTK label symbols" -\image latex symbols.png "FLTK label symbols" width=10cm - -<!-- NEED 2in --> - -The @ sign may also be followed by the following optional -"formatting" characters, in this order: - -\li '#' forces square scaling, rather than distortion to the widget's shape. - -\li +[1-9] or -[1-9] tweaks the scaling a little bigger or smaller. - -\li '$' flips the symbol horizontally, '%' flips it vertically. - -\li [0-9] - rotates by a multiple of 45 degrees. '5' and '6' do no rotation - while the others point in the direction of that key on a numeric keypad. - '0', followed by four more digits rotates the symbol by that amount in - degrees. - -Thus, to show a very large arrow pointing downward you would use the -label string "@+92->". - -\par align() - -The \p align() method positions the label. The following -constants are defined and may be OR'd together as needed: - -\li \p FL_ALIGN_CENTER - center the label in the widget. -\li \p FL_ALIGN_TOP - align the label at the top of the widget. -\li \p FL_ALIGN_BOTTOM - align the label at the bottom of the widget. -\li \p FL_ALIGN_LEFT - align the label to the left of the widget. -\li \p FL_ALIGN_RIGHT - align the label to the right of the widget. -\li \p FL_ALIGN_LEFT_TOP - The label appears to the left of the widget, aligned at the top. Outside labels only. -\li \p FL_ALIGN_RIGHT_TOP - The label appears to the right of the widget, aligned at the top. Outside labels only. -\li \p FL_ALIGN_LEFT_BOTTOM - The label appears to the left of the widget, aligned at the bottom. Outside labels only. -\li \p FL_ALIGN_RIGHT_BOTTOM - The label appears to the right of the widget, aligned at the bottom. Outside labels only. -\li \p FL_ALIGN_INSIDE - align the label inside the widget. -\li \p FL_ALIGN_CLIP - clip the label to the widget's bounding box. -\li \p FL_ALIGN_WRAP - wrap the label text as needed. -\li \p FL_ALIGN_TEXT_OVER_IMAGE - show the label text over the image. -\li \p FL_ALIGN_IMAGE_OVER_TEXT - show the label image over the text (default). -\li \p FL_ALIGN_IMAGE_NEXT_TO_TEXT - The image will appear to the left of the text. -\li \p FL_ALIGN_TEXT_NEXT_TO_IMAGE - The image will appear to the right of the text. -\li \p FL_ALIGN_IMAGE_BACKDROP - The image will be used as a background for the widget. - -\anchor common_labeltype -\par labeltype() - -The \p labeltype() method sets the type of the label. The -following standard label types are included: - -\li \p FL_NORMAL_LABEL - draws the text. -\li \p FL_NO_LABEL - does nothing. -\li \p FL_SHADOW_LABEL - draws a drop shadow under the text. -\li \p FL_ENGRAVED_LABEL - draws edges as though the text is engraved. -\li \p FL_EMBOSSED_LABEL - draws edges as thought the text is raised. -\li \p FL_ICON_LABEL - draws the icon associated with the text. - -\par image() and deimage() - -The \p image() and \p deimage() methods set an image that -will be displayed with the widget. The \p deimage() method sets the -image that is shown when the widget is inactive, while the \p image() -method sets the image that is shown when the widget is active. - -To make an image you use a subclass of -\ref ssect_Fl_Image "Fl_Image". - -\par Making Your Own Label Types - -Label types are actually indexes into a table of functions -that draw them. The primary purpose of this is to use this to -draw the labels in ways inaccessible through the -fl_font() mechanism (e.g. <tt>FL_ENGRAVED_LABEL</tt>) or -with program-generated letters or symbology. - -<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> -<TR> - <TD><B>Note:</B> - <P>This interface has changed in FLTK 2.0! - </TD> -</TR> -</TABLE></CENTER> - -\par Label Type Functions - -To setup your own label type you will need to write two -functions: one to draw and one to measure the label. The draw -function is called with a pointer to a Fl_Label -structure containing the label information, the bounding box for -the label, and the label alignment: - -\code -void xyz_draw(const Fl_Label *label, int x, int y, int w, int h, Fl_Align align) { -... -} -\endcode - -The label should be drawn \e inside this bounding box, -even if \p FL_ALIGN_INSIDE is not enabled. The function -is not called if the label value is \p NULL. - -The measure function is called with a pointer to a -Fl_Label structure and references to the width and -height: - -\code -void xyz_measure(const Fl_Label *label, int &w, int &h) { -... -} -\endcode - -The function should measure the size of the label and set -\p w and \p h to the size it will occupy. - -\par Adding Your Label Type - -The Fl::set_labeltype() method creates a label type -using your draw and measure functions: - -\code -#define XYZ_LABEL FL_FREE_LABELTYPE - -Fl::set_labeltype(XYZ_LABEL, xyz_draw, xyz_measure); -\endcode - -The label type number \p n can be any integer value -starting at the constant \p FL_FREE_LABELTYPE. Once you -have added the label type you can use the \p labeltype() -method to select your label type. - -The Fl::set_labeltype() method can also be used to overload -an existing label type such as \p FL_NORMAL_LABEL. - -\par Making your own symbols - -It is also possible to define your own drawings and add -them to the symbol list, so they can be rendered as part of -any label. - -To create a new symbol, you implement a drawing function -<tt>void drawit(Fl_Color c)</tt> which typically uses the -functions described in \ref ssect_Complex -to generate a vector shape inside a two-by-two units sized box -around the origin. This function is then linked into the symbols -table using fl_add_symbol(): - -\code -int fl_add_symbol(const char *name, void (*drawit)(Fl_Color), int scalable) -\endcode - -\p name is the name of the symbol without the "@"; \p scalable -must be set to 1 if the symbol is generated using scalable vector drawing -functions. - -\code -int fl_draw_symbol(const char *name,int x,int y,int w,int h,Fl_Color col) -\endcode - -This function draws a named symbol fitting the given rectangle. - -\section common_callbacks Callbacks - -Callbacks are functions that are called when the value of a -widget changes. A callback function is sent a Fl_Widget -pointer of the widget that changed and a pointer to data that -you provide: - -\code -void xyz_callback(Fl_Widget *w, void *data) { -... -} -\endcode - -The \p callback() method sets the callback function for a -widget. You can optionally pass a pointer to some data needed for the -callback: - -\code -int xyz_data; - -button->callback(xyz_callback, &xyz_data); -\endcode - -Normally callbacks are performed only when the value of the -widget changes. You can change this using the Fl_Widget::when() -method: - -\code -button->when(FL_WHEN_NEVER); -button->when(FL_WHEN_CHANGED); -button->when(FL_WHEN_RELEASE); -button->when(FL_WHEN_RELEASE_ALWAYS); -button->when(FL_WHEN_ENTER_KEY); -button->when(FL_WHEN_ENTER_KEY_ALWAYS); -button->when(FL_WHEN_CHANGED | FL_WHEN_NOT_CHANGED); -\endcode - -<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> -<TR> - <TD><B>Note:</B> - - You cannot delete a widget inside a callback, as the - widget may still be accessed by FLTK after your callback - is completed. Instead, use the Fl::delete_widget() - method to mark your widget for deletion when it is safe - to do so. - - <B>Hint:</B> - - Many programmers new to FLTK or C++ try to use a - non-static class method instead of a static class method - or function for their callback. Since callbacks are done - outside a C++ class, the <tt>this</tt> pointer is not - initialized for class methods. - - To work around this problem, define a static method - in your class that accepts a pointer to the class, and - then have the static method call the class method(s) as - needed. The data pointer you provide to the - \p callback() method of the widget can be a - pointer to the instance of your class. - -\code -class Foo { - void my_callback(Fl_Widget *w); - static void my_static_callback(Fl_Widget *w, void *f) { ((Foo *)f)->my_callback(w); } - ... -} - -... - -w->callback(my_static_callback, (void *)this); -\endcode - </TD> -</TR> -</TABLE></CENTER> - -\section common_shortcuts Shortcuts - -Shortcuts are key sequences that activate widgets such as -buttons or menu items. The \p shortcut() method sets the -shortcut for a widget: - -\code -button->shortcut(FL_Enter); -button->shortcut(FL_SHIFT + 'b'); -button->shortcut(FL_CTRL + 'b'); -button->shortcut(FL_ALT + 'b'); -button->shortcut(FL_CTRL + FL_ALT + 'b'); -button->shortcut(0); // no shortcut -\endcode - -The shortcut value is the key event value - the ASCII value -or one of the special keys described in -\ref enumerations_event_key -combined with any modifiers like \p Shift , \p Alt , and \p Control. - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="basics.html"> - [Prev] - FLTK Basics - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="editor.html"> - Designing a Simple Text Editor - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/counter.png b/branch-3.0-2011/documentation/src/counter.png Binary files differdeleted file mode 100644 index 3c51f6215..000000000 --- a/branch-3.0-2011/documentation/src/counter.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/cubeview.png b/branch-3.0-2011/documentation/src/cubeview.png Binary files differdeleted file mode 100644 index 877be186c..000000000 --- a/branch-3.0-2011/documentation/src/cubeview.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/development.dox b/branch-3.0-2011/documentation/src/development.dox deleted file mode 100644 index 11fe2c467..000000000 --- a/branch-3.0-2011/documentation/src/development.dox +++ /dev/null @@ -1,404 +0,0 @@ -/** - - \page development Developer Information - -This chapter describes FLTK development and documentation. - -\note documentation with doxygen will be described here. - - -<H2>Example</H2> - -\note - -In the following code example(s) "*" will be replaced by "#" -as a temporary solution. - -\code - - -/## \file - Fl_Clock, Fl_Clock_Output widgets . #/ - - -/## - \class Fl_Clock_Output - \brief This widget can be used to display a program-supplied time. - - The time shown on the clock is not updated. To display the current time, - use Fl_Clock instead. - - \image html clock.png - \image latex clock.png "" width=10cm - \image html round_clock.png - \image latex clock.png "" width=10cm - \image html round_clock.png "" width=10cm #/ - - /## - Returns the displayed time. - Returns the time in seconds since the UNIX epoch (January 1, 1970). - \see value(ulong) - #/ - ulong value() const {return value_;} - -/## - Set the displayed time. - Set the time in seconds since the UNIX epoch (January 1, 1970). - \param[in] v seconds since epoch - \see value() - #/ -void Fl_Clock_Output::value(ulong v) { - [...] -} - -/## - Create an Fl_Clock widget using the given position, size, and label string. - The default boxtype is \c FL_NO_BOX. - \param[in] X, Y, W, H position and size of the widget - \param[in] L widget label, default is no label - #/ -Fl_Clock::Fl_Clock(int X, int Y, int W, int H, const char #L) - : Fl_Clock_Output(X, Y, W, H, L) {} - -/## - Create an Fl_Clock widget using the given boxtype, position, size, and - label string. - \param[in] t boxtype - \param[in] X, Y, W, H position and size of the widget - \param[in] L widget label, default is no label - #/ -Fl_Clock::Fl_Clock(uchar t, int X, int Y, int W, int H, const char #L) - : Fl_Clock_Output(X, Y, W, H, L) { - type(t); - box(t==FL_ROUND_CLOCK ? FL_NO_BOX : FL_UP_BOX); -} - - -\endcode - - -\note - -From Duncan: (will be removed later, just for now as a reminder) - -5. I've just added comments for the fl_color_chooser() functions, and - in order to keep them and the general Function Reference information - for them together, I created a new doxygen group, and used \\ingroup - in the three comment blocks. This creates a new Modules page (which - may not be what we want) with links to it from the File Members and - Fl_Color_Chooser.H pages. It needs a bit more experimentation on my - part unless someone already knows how this should be handled. (Maybe - we can add it to a functions.dox file that defines a functions group - and do that for all of the function documentation?) - -\b Update: the trick is not to create duplicate entries in a new group, but - to move the function information into the doxygen comments for the - class, and use the navigation links provided. Simply using \\relatesalso - as the first doxygen command in the function's comment puts it in the - appropriate place. There is no need to have \\defgroup and \\ingroup as - well, and indeed they don't work. So, to summarize: -\code -Gizmo.H - /## \class Gizmo - A gizmo that does everything - #/ - class Gizmo { - etc - }; - extern int popup_gizmo(...); - -Gizmo.cxx: - /## \relatesalso Gizmo - Pops up a gizmo dialog with a Gizmo in it - #/ - int popup_gizmo(...); -\endcode - -<H3>Example comment:</H3> - -You can use HTML comment statements to embed comments in doxygen comment blocks. -These comments will not be visible in the generated document. - - The following text is a developer comment. - <!-- *** This *** is *** invisible *** --> - This will be visible again. - -\code - The following text is a developer comment. - <!-- *** This *** is *** invisible *** --> - This will be visible again. -\endcode - - -<H3>Different Headlines:</H3> - -\code - <H1>Headline in big text (H1)</H1> - <H2>Headline in big text (H2)</H2> - <H3>Headline in big text (H3)</H3> - <H4>Headline in big text (H4)</H4> -\endcode - - <H1>Headline in big text (H1)</H1> - <H2>Headline in big text (H2)</H2> - <H3>Headline in big text (H3)</H3> - <H4>Headline in big text (H4)</H4> - - -\section development_non-ascii Non-ASCII characters - - if you came here from below: back to \ref development_links - -\code - Doxygen understands many HTML quoting characters like - ", ü, ç, Ç, but not all HTML quoting characters. -\endcode - -This will appear in the document: - - Doxygen understands many HTML quoting characters like - ", ü, ç, Ç, but not all HTML quoting characters. - -For further informations about quoting see - \b http://www.stack.nl/~dimitri/doxygen/htmlcmds.html - -<H3>Example with UTF-8 encoded text</H3> - -\code - - <P>Assuming that the following source code was written on MS Windows, - this example will output the correct label on OS X and X11 as well. - Without the conversion call, the label on OS X would read - <tt>Fahrvergn¸gen</tt> with a deformed umlaut u ("cedille", - html "¸"). - \#code - btn = new Fl_Button(10, 10, 300, 25); - btn->copy_label(fl_latin1_to_local("Fahrvergnügen")); - \#endcode - - \note If your application uses characters that are not part of both - encodings, or it will be used in areas that commonly use different - code pages, you might consider upgrading to FLTK 2 which supports - UTF-8 encoding. - - \todo This is an example todo entry, please ignore ! - -\endcode - -This will appear in the document: - - <P>Assuming that the following source code was written on MS Windows, - this example will output the correct label on OS X and X11 as well. - Without the conversion call, the label on OS X would read - <tt>Fahrvergn¸gen</tt> with a deformed umlaut u ("cedille", - html "¸"). - \#code - btn = new Fl_Button(10, 10, 300, 25); - btn->copy_label(fl_latin1_to_local("Fahrvergnügen")); - \#endcode - - \note If your application uses characters that are not part of both - encodings, or it will be used in areas that commonly use different - code pages, you might consider upgrading to FLTK 2 which supports - UTF-8 encoding. - - \todo This is an example todo entry, please ignore ! - -\section development_structure Document Structure - - \li \b \\page creates a named page - \li \b \\section creates a named section within that page - \li \b \\subsection creates a named subsection within the current section - \li \b \\subsubsection creates a named subsubsection within the current subsection - -All these statements take a "name" as their first argument, and a title -as their second argument. The title can contain spaces. - -The page, section, and subsection titles are formatted in blue color and -a size like \b "<H1>", \b "<H2>", and \b "<H3>", and \b "<H4>", respectively. - -By <b>FLTK documentation convention</b>, a file like this one with a doxygen -documentation chapter has the name <b>"<chapter>.dox".</b> -The \b \\page statement at the top of the page is -<b>"\page <chapter> This is the title"</b>. -Sections within a documentation page must be called \b "<chapter>_<section>", -where \b "<chapter>" is the name part of the file, and \b "<section>" is a -unique section name within the page that can be referenced in links. The -same for subsections and subsubsections. - -These doxygen page and section commands work only in special documentation -chapters, not within normal source or header documentation blocks. However, -links \b from normal (e.g. class) documentation \b to documentation sections -\b do \b work. - -This page has - \code - \page development I - Developer Information - \endcode -at its top. - -This section is - \code - \section development_structure Document structure - \endcode - -The following section is - \code - \section development_links Creating Links - \endcode - - -\section development_links Creating Links - -Links to other documents and external links can be embedded with - -- doxygen \\ref links to other doxygen \\page, \\section, - \\subsection and \\anchor locations -- HTML links without markup - doxygen creates "http://..." - links automatically -- standard, non-Doxygen, HTML links - -\code - -- see chapter \ref unicode creates a link to the named chapter - unicode that has been created with a \page statement. - -- For further informations about quoting see - http://www.stack.nl/~dimitri/doxygen/htmlcmds.html - -- see <a href="http://www.nedit.org/">Nedit</a> creates - a standard HTML link - -\endcode - -appears as: - -- see chapter \ref unicode creates a link to the named chapter - unicode that has been created with a \\page statement. - -- For further informations about quoting see - http://www.stack.nl/~dimitri/doxygen/htmlcmds.html - -- see <a href="http://www.nedit.org/">Nedit</a> creates - a standard HTML link - - -\section development_paragraphs Paragraph Layout - -There is no real need to use HTML \<P\> and \</P\> tags within the text -to tell doxygen to start or stop a paragraph. In most cases, when doxygen -encounters a blank line or some, but not all, \b \\commands in the text it -knows that it as reached the start or end of a paragraph. Doxygen also -offers the \b \\par command for special paragraph handling. It can be used -to provide a paragraph title and also to indent a paragraph. Unfortunately -\b \\par won't do what you expect if you want to have doxygen links and -sometimes html tags don't work either. - - <!-- use verbatim rather than code to avoid links to code reference --> - \verbatim - \par Normal Paragraph with title - - This paragraph will have a title, but because there is a blank line - between the \par and the text, it will have the normal layout. - - \par Indented Paragraph with title - This paragraph will also have a title, but because there is no blank - line between the \par and the text, it will be indented. - - \par - It is also possible to have an indented paragraph without title. - This is how you indent subsequent paragraphs. - - \par No link to Fl_Widget::draw() - Note that the paragraph title is treated as plain text. - Doxygen type links will not work. - HTML characters and tags may or may not work. - - Fl_Widget::draw() links and "html" tags work<br> - \par - Use a single line ending with <br> for complicated paragraph titles. - \endverbatim - -The above code produces the following paragraphs: - - \par Normal Paragraph with title - - This paragraph will have a title, but because there is a blank line - between the \\par and the text, it will have the normal layout. - - \par Indented Paragraph with title - This paragraph will also have a title, but because there is no blank - line between the \\par and the text, it will be indented. - - \par - It is also possible to have an indented paragraph without title. - This is how you indent subsequent paragraphs. - - \par No link to Fl_Widget::draw() - Note that the paragraph title is treated as plain text. - Doxygen type links will not work. - HTML characters and tags may or may not work. - - Fl_Widget::draw() links and "html" tags work<br> - \par - Use a single line ending with \<br\> for complicated paragraph titles. - - -\section development_navigation_test Navigation Elements - -Each introduction (tutorial) page ends with navigation elements. These -elements must only be included in the html documentation, therefore -they must be separated with \\htmlonly and \\endhtmlonly. - -The following code gives the navigation bar at the bottom of this page: - -\verbatim -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="migration_1_3.html"> - [Prev] - Migrating Code from FLTK 1.1 to 1.3 - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="license.html"> - Software License - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly -\endverbatim - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="migration_1_3.html"> - [Prev] - Migrating Code from FLTK 1.1 to 1.3 - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="license.html"> - Software License - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/dial.png b/branch-3.0-2011/documentation/src/dial.png Binary files differdeleted file mode 100644 index efc2aadc9..000000000 --- a/branch-3.0-2011/documentation/src/dial.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/drawing.dox b/branch-3.0-2011/documentation/src/drawing.dox deleted file mode 100644 index 22e8ce8a8..000000000 --- a/branch-3.0-2011/documentation/src/drawing.dox +++ /dev/null @@ -1,1031 +0,0 @@ -/** - - \page drawing Drawing Things in FLTK - -This chapter covers the drawing functions that are provided with FLTK. - -\section sect_WhenCanYouDraw When Can You Draw Things in FLTK? - -There are only certain places you can execute drawing code in FLTK. -Calling these functions at other places will result in undefined behavior! - -\li The most common place is inside the virtual Fl_Widget::draw() method. - To write code here, you must subclass one of the existing Fl_Widget - classes and implement your own version of draw(). - -\li You can also create custom \ref common_boxtypes "boxtypes" and - \ref common_labeltype "labeltypes". These involve writing small - procedures that can be called by existing Fl_Widget::draw() methods. - These "types" are identified by an 8-bit index that is stored in the - widget's \p box(), \p labeltype(), and possibly other properties. - -\li You can call Fl_Window::make_current() to do incremental update of a - widget. Use Fl_Widget::window() to find the window. - - -\section sect_DrawingFunctions Drawing Functions - -To use the drawing functions you must first include the <FL/fl_draw.H> -header file. FLTK provides the following types of drawing functions: - -\li \ref ssect_Boxes -\li \ref ssect_Clipping -\li \ref drawing_colors -\li \ref ssect_Lines -\li \ref ssect_Fast -\li \ref ssect_Complex -\li \ref ssect_Text -\li \ref ssect_Fonts -\li \ref ssect_CharacterEncoding -\li \ref ssect_Overlay -\li \ref drawing_images -\li \ref ssect_DirectImageDrawing -\li \ref ssect_DirectImageReading -\li \ref ssect_Fl_Image -\li \ref ssect_Offscreen - -\subsection ssect_Boxes Boxes - -FLTK provides three functions that can be used to draw boxes for buttons -and other UI controls. Each function uses the supplied upper-lefthand corner -and width and height to determine where to draw the box. - -void fl_draw_box(Fl_Boxtype b, int x, int y, int w, int h, Fl_Color c); - -\par -The \p %fl_draw_box() function draws a standard boxtype \p b -in the specified color \p c. - -\anchor drawing_fl_frame -void fl_frame(const char *s, int x, int y, int w, int h) <br> -void fl_frame2(const char *s, int x, int y, int w, int h) - -\par -The \p %fl_frame() and \p %fl_frame2() functions draw a series of -line segments around the given box. The string \p s must contain groups -of 4 letters which specify one of 24 standard grayscale values, -where 'A' is black and 'X' is white. -The results of calling these functions with a string that is not a -multiple of 4 characters in length are undefined. - -\par -The only difference between \p %fl_frame() and \p %fl_frame2() -is the order of the line segments: - - For \p %fl_frame() the order of each set of 4 characters is: - top, left, bottom, right. - - For \p %fl_frame2() the order of each set of 4 characters is: - bottom, right, top, left. - -\par -Note that -\ref common_fl_frame "fl_frame(Fl_Boxtype b)" -is described in the \ref common_boxtypes section. - - -\subsection ssect_Clipping Clipping - -You can limit all your drawing to a rectangular region by calling -\p %fl_push_clip(), and put the drawings back by using -\p %fl_pop_clip(). -This rectangle is measured in pixels and is unaffected by the current -transformation matrix. - -In addition, the system may provide clipping when updating windows -which may be more complex than a simple rectangle. - -void fl_push_clip(int x, int y, int w, int h) <br> -void fl_clip(int x, int y, int w, int h) - -\par -Intersect the current clip region with a rectangle and push this new -region onto the stack. - -\par -The \p %fl_clip() version is deprecated and -will be removed from future releases. - -void fl_push_no_clip() - -\par -Pushes an empty clip region on the stack so nothing will be clipped. - -void fl_pop_clip() - -\par -Restore the previous clip region. - -\par -\b Note: -You must call \p %fl_pop_clip() once for every time you call -\p %fl_push_clip(). -If you return to FLTK with the clip stack not empty unpredictable results -occur. - -int fl_not_clipped(int x, int y, int w, int h) - -\par -Returns non-zero if any of the rectangle intersects the current clip -region. If this returns 0 you don't have to draw the object. - -\par -\b Note: -Under X this returns 2 if the rectangle is partially clipped, -and 1 if it is entirely inside the clip region. - -int fl_clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, int &H) - -\par -Intersect the rectangle <tt>x,y,w,h</tt> with the current -clip region and returns the bounding box of the result in -<tt>X,Y,W,H</tt>. Returns non-zero if the resulting rectangle is -different than the original. This can be used to limit the -necessary drawing to a rectangle. \c W and \c H are -set to zero if the rectangle is completely outside the region. - -void fl_clip_region(Fl_Region r) <br> -Fl_Region fl_clip_region() - -\par -Replace the top of the clip stack with a clipping region of any shape. -Fl_Region is an operating system specific type. The second form returns -the current clipping region. - - -\section drawing_colors Colors - -FLTK manages colors as 32-bit unsigned integers, encoded as RGBI. -When the RGB bytes are non-zero, the value is treated as RGB. -If these bytes are zero, the I byte will be used as an index -into the colormap. - -Values from 0 to 255, i.e. the I index value, represent -colors from the FLTK 1.3.x standard colormap -and are allocated as needed on screens without TrueColor support. -The \b Fl_Color enumeration type defines the -standard colors and color cube for the first 256 colors. All of -these are named with symbols in -\ref enumerations "<FL/Enumerations.H>". - -Color values greater than 255 are treated as 24-bit RGB -values. These are mapped to the closest color supported by the -screen, either from one of the 256 colors in the FLTK 1.3.x -colormap or a direct RGB value on TrueColor screens. - -Fl_Color fl_rgb_color(uchar r, uchar g, uchar b) <br> -Fl_Color fl_rgb_color(uchar grayscale) - -\par -Generate Fl_Color out of specified -8-bit RGB values or one 8-bit grayscale value. - -void fl_color(Fl_Color c) <br> -void fl_color(int c) - -\par -Sets the color for all subsequent drawing operations. -Please use the first form: -the second form is only provided for back compatibility. - -\par -For colormapped displays, a color cell will be allocated out -of \p fl_colormap the first time you use a color. If the -colormap fills up then a least-squares algorithm is used to find -the closest color. - -Fl_Color fl_color() - -\par -Returns the last color that was set using \p %fl_color(). -This can be used for state save/restore. - -void fl_color(uchar r, uchar g, uchar b) - -\par -Set the color for all subsequent drawing operations. The -closest possible match to the RGB color is used. The RGB color -is used directly on TrueColor displays. For colormap visuals the -nearest index in the gray ramp or color cube is used. - -unsigned Fl::get_color(Fl_Color i) <br> -void Fl::get_color(Fl_Color i, uchar &red, uchar &green, uchar &blue) - -\par -Generate RGB values from a colormap index value \p i. -The first returns the RGB as a 32-bit unsigned integer, -and the second decomposes the RGB into three 8-bit values. -\todo work out why Fl::get_color() does not give links! - -Fl::get_system_colors() <br> -Fl::foreground() <br> -Fl::background() <br> -Fl::background2() - -\par -The first gets color values from the user preferences or the system, -and the other routines are used to apply those values. - -Fl::own_colormap() <br> -Fl::free_color(Fl_Color i, int overlay) <br> -Fl::set_color(Fl_Color i, unsigned c) - -\par -\p Fl::own_colormap() is used to install a local colormap [X11 only]. -\par -\p Fl::free_color() and \p Fl::set_color() are used to remove and replace -entries from the colormap. -\todo work out why these do not give links! - -There are two predefined graphical interfaces for choosing colors. -The function fl_show_colormap() shows a table of colors and returns an -Fl_Color index value. -The Fl_Color_Chooser widget provides a standard RGB color chooser. - -As the Fl_Color encoding maps to a 32-bit unsigned integer representing -RGBI, it is also possible to specify a color using a hex constant as a -color map index: -<pre> -// COLOR MAP INDEX -color(0x000000II) - ------ | - | | - | Color map index (8 bits) - Must be zero -</pre> -\code -button->color(0x000000ff); // colormap index #255 (FL_WHITE) -\endcode - -or specify a color using a hex constant for the RGB components: -<pre> -// RGB COLOR ASSIGNMENTS -color(0xRRGGBB00) - | | | | - | | | Must be zero - | | Blue (8 bits) - | Green (8 bits) - Red (8 bits) -</pre> -\code -button->color(0xff000000); // RGB: red -button->color(0x00ff0000); // RGB: green -button->color(0x0000ff00); // RGB: blue -button->color(0xffffff00); // RGB: white -\endcode - -\note -If TrueColor is not available, any RGB colors will be set to -the nearest entry in the colormap. - -\subsection ssect_Lines Line Dashes and Thickness - -FLTK supports drawing of lines with different styles and -widths. Full functionality is not available under Windows 95, 98, -and Me due to the reduced drawing functionality these operating -systems provide. - -void fl_line_style(int style, int width, char* dashes) - -\par -Set how to draw lines (the "pen"). If you change this it is your -responsibility to set it back to the default with -\p fl_line_style(0). - -\par -\b Note: -Because of how line styles are implemented on MS Windows systems, you -\e must set the line style \e after setting the drawing color. -If you set the -color after the line style you will lose the line style settings! - -\par -\p style is a bitmask which is a bitwise-OR of the following -values. If you don't specify a dash type you will get a solid -line. If you don't specify a cap or join type you will get a -system-defined default of whatever value is fastest. - -\par -\li <tt>FL_SOLID -------</tt> -\li <tt>FL_DASH - - - -</tt> -\li <tt>FL_DOT .......</tt> -\li <tt>FL_DASHDOT - . - .</tt> -\li <tt>FL_DASHDOTDOT - .. -</tt> -\li <tt>FL_CAP_FLAT</tt> -\li <tt>FL_CAP_ROUND</tt> -\li <tt>FL_CAP_SQUARE</tt> (extends past end point 1/2 line width) -\li <tt>FL_JOIN_MITER</tt> (pointed) -\li <tt>FL_JOIN_ROUND</tt> -\li <tt>FL_JOIN_BEVEL</tt> (flat) - -\par -\p width is the number of pixels thick to draw the lines. -Zero results in the system-defined default, which on both X and -Windows is somewhat different and nicer than 1. - -\par -\p dashes is a pointer to an array of dash lengths, measured in -pixels. The first location is how long to draw a solid portion, the -next is how long to draw the gap, then the solid, etc. It is -terminated with a zero-length entry. A \p NULL pointer or a zero-length -array results in a solid line. Odd array sizes are not supported and -result in undefined behavior. - -\par -\b Note: -The dashes array does not work under Windows 95, 98, or Me, since those -operating systems do not support complex line styles. - - -\subsection ssect_Fast Drawing Fast Shapes - -These functions are used to draw almost all the FLTK widgets. -They draw on exact pixel boundaries and are as fast as possible. -Their behavior is duplicated exactly on all platforms FLTK is -ported. It is undefined whether these are affected by the -\ref ssect_Complex "transformation matrix", -so you should only call these while the matrix is set to the -identity matrix (the default). - -void fl_point(int x, int y) - -\par -Draw a single pixel at the given coordinates. - -void fl_rectf(int x, int y, int w, int h) <br> -void fl_rectf(int x, int y, int w, int h) - -\par -Color a rectangle that exactly fills the given bounding box. - -void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b) - -\par -Color a rectangle with "exactly" the passed -<tt>r,g,b</tt> color. On screens with less than 24 bits of -color this is done by drawing a solid-colored block using -\ref drawing_fl_draw_image "fl_draw_image()" -so that the correct color shade is produced. - -void fl_rect(int x, int y, int w, int h) <br> -void fl_rect(int x, int y, int w, int h, Fl_Color c) - -\par -Draw a 1-pixel border \e inside this bounding box. - -void fl_line(int x, int y, int x1, int y1) <br> -void fl_line(int x, int y, int x1, int y1, int x2, int y2) - -\par -Draw one or two lines between the given points. - -void fl_loop(int x, int y, int x1, int y1, int x2, int y2) <br> -void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) - -\par -Outline a 3 or 4-sided polygon with lines. - -void fl_polygon(int x, int y, int x1, int y1, int x2, int y2) <br> -void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) - -\par -Fill a 3 or 4-sided polygon. The polygon must be convex. - -void fl_xyline(int x, int y, int x1) <br> -void fl_xyline(int x, int y, int x1, int y2) <br> -void fl_xyline(int x, int y, int x1, int y2, int x3) - -\par -Draw horizontal and vertical lines. A horizontal line is -drawn first, then a vertical, then a horizontal. - -void fl_yxline(int x, int y, int y1) <br> -void fl_yxline(int x, int y, int y1, int x2) <br> -void fl_yxline(int x, int y, int y1, int x2, int y3) - -\par -Draw vertical and horizontal lines. A vertical line is drawn -first, then a horizontal, then a vertical. - -void fl_arc(int x, int y, int w, int h, double a1, double a2) <br> -void fl_pie(int x, int y, int w, int h, double a1, double a2) - -\par -Draw ellipse sections using integer coordinates. These -functions match the rather limited circle drawing code provided -by X and MS Windows. The advantage over using -\ref drawing_fl_arc "fl_arc()" -with floating point -coordinates is that they are faster because they often use the -hardware, and they draw much nicer small circles, since the -small sizes are often hard-coded bitmaps. - -\par -If a complete circle is drawn it will fit inside the passed bounding -box. The two angles are measured in degrees counterclockwise from -3'oclock and are the starting and ending angle of the arc, \p a2 -must be greater or equal to \p a1. - -\par -\p %fl_arc() draws a series of lines to approximate the arc. -Notice that the integer version of \p %fl_arc() has a different -number of arguments to the other -\ref drawing_fl_arc "fl_arc()" -function described later in this chapter. - -\par -\p %fl_pie() draws a filled-in pie slice. This slice may -extend outside the line drawn by \p %fl_arc(); to avoid this -use \p w-1 and \p h-1. - -\todo -add an Fl_Draw_Area_Cb typedef to allow fl_scroll(...) to be doxygenated? - -void fl_scroll(int X, int Y, int W, int H, int dx, int dy, void (*draw_area)(void*, int,int,int,int), void* data) - -\par -Scroll a rectangle and draw the newly exposed portions. The contents -of the rectangular area is first shifted by \p dx and -\p dy pixels. The callback is then called for every newly -exposed rectangular area, - - -\subsection ssect_Complex Drawing Complex Shapes - -The complex drawing functions let you draw arbitrary shapes -with 2-D linear transformations. The functionality matches that -found in the Adobe® PostScript&tm; language. The -exact pixels that are filled are less defined than for the fast -drawing functions so that FLTK can take advantage of drawing -hardware. On both X and MS Windows the transformed vertices are -rounded to integers before drawing the line segments: this -severely limits the accuracy of these functions for complex -graphics, so use OpenGL when greater accuracy and/or performance -is required. - -void fl_push_matrix() <br> -void fl_pop_matrix() - -\par -Save and restore the current transformation. The maximum -depth of the stack is 32 entries. - -void fl_scale(double x,double y) <br> -void fl_scale(double x) <br> -void fl_translate(double x,double y) <br> -void fl_rotate(double d) <br> -void fl_mult_matrix(double a,double b,double c,double d,double x,double y) - -\par -Concatenate another transformation onto the current one. The rotation -angle is in degrees (not radians) and is counter-clockwise. - -double fl_transform_x(double x, double y) <br> -double fl_transform_y(double x, double y) <br> -double fl_transform_dx(double x, double y) <br> -double fl_transform_dy(double x, double y) <br> -void fl_transformed_vertex(double xf, double yf) - -\par -Transform a coordinate or a distance using the current transformation matrix. -After transforming a coordinate pair, it can be added to the vertex -list without any further translations using \p %fl_transformed_vertex(). - -void fl_begin_points() <br> -void fl_end_points() - -\par -Start and end drawing a list of points. Points are added to -the list with \p %fl_vertex(). - -void fl_begin_line() <br> -void fl_end_line() - -\par -Start and end drawing lines. - -void fl_begin_loop() <br> -void fl_end_loop() - -\par -Start and end drawing a closed sequence of lines. - -void fl_begin_polygon() <br> -void fl_end_polygon() - -\par -Start and end drawing a convex filled polygon. - -void fl_begin_complex_polygon() <br> -void fl_gap() <br> -void fl_end_complex_polygon() - -\par -Start and end drawing a complex filled polygon. This polygon -may be concave, may have holes in it, or may be several -disconnected pieces. Call \p %fl_gap() to separate loops of -the path. It is unnecessary but harmless to call -\p %fl_gap() before the first vertex, after the last one, -or several times in a row. - -\par -\p %fl_gap() should only be called between -\p %fl_begin_complex_polygon() and -\p %fl_end_complex_polygon(). -To outline the polygon, use -\p %fl_begin_loop() and replace each -\p %fl_gap() with a -\p %fl_end_loop();%fl_begin_loop() pair. - -\par -\b Note: -For portability, you should only draw polygons that appear the same whether -"even/odd" or "non-zero" winding rules are used to fill them. Holes should -be drawn in the opposite direction of the outside loop. - -void fl_vertex(double x,double y) - -\par -Add a single vertex to the current path. - -void fl_curve(double X0, double Y0, double X1, double Y1, double X2, double Y2, double X3, double Y3) - -\par -Add a series of points on a Bezier curve to the path. The curve ends -(and two of the points) are at <tt>X0,Y0</tt> and <tt>X3,Y3</tt>. - -\anchor drawing_fl_arc -void fl_arc(double x, double y, double r, double start, double end) - -\par -Add a series of points to the current path on the arc of a -circle; you can get elliptical paths by using scale and rotate -before calling \p %fl_arc(). -The center of the circle is given by \p x and \p y, -and \p r is its radius. -\p %fl_arc() -takes \p start and \p end angles that are measured -in degrees counter-clockwise from 3 o'clock. -If \p end is less than \p start then it draws the arc in a clockwise -direction. - -void fl_circle(double x, double y, double r) - -\par -\p fl_circle(...) is equivalent to \p fl_arc(...,0,360) but may -be faster. It must be the \e only thing in the path: if you want -a circle as part of a complex polygon you must use \p %fl_arc(). - -\par -\b Note: -\p %fl_circle() draws incorrectly if the transformation is both rotated and -non-square scaled. - -\subsection ssect_Text Drawing Text - -All text is drawn in the -\ref drawing_fl_font "current font". -It is undefined whether this location or the characters are -modified by the current transformation. - -void fl_draw(const char *, int x, int y) <br> -void fl_draw(const char *, int n, int x, int y) - -\par -Draw a nul-terminated string or an array of \p n characters -starting at the given location. Text is aligned to the left and to -the baseline of the font. To align to the bottom, subtract -\p %fl_descent() from \p y. -To align to the top, subtract \p %fl_descent() and add \p %fl_height(). -This version of \p %fl_draw() provides direct access to -the text drawing function of the underlying OS. It does not apply any -special handling to control characters. - -void fl_draw(const char* str, int x, int y, int w, int h, Fl_Align align, Fl_Image* img, int draw_symbols) - -\par -Fancy string drawing function which is used to draw all the -labels. The string is formatted and aligned inside the passed -box. Handles '\\t' and '\\n', expands all other control -characters to ^X, and aligns inside or against the edges of the -box described by \p x, \p y, \p w and \p h. -See Fl_Widget::align() for values for \p align. -The value \p FL_ALIGN_INSIDE is ignored, as this function always -prints inside the box. - -\par -If \p img is provided and is not \p NULL, the -image is drawn above or below the text as specified by the -\p align value. - -\par -The \p draw_symbols argument specifies whether or not -to look for symbol names starting with the "@" character. - -\par -The text length is limited to 1024 characters per line. - -void fl_measure(const char *str, int& w, int& h, int draw_symbols) - -\par -Measure how wide and tall the string will be when printed by -the \p fl_draw(...align) function. -If the incoming \p w is non-zero it will wrap to that width. - -int fl_height() - -\par -Recommended minimum line spacing for the current font. You -can also just use the value of \p size passed to -\ref drawing_fl_font "fl_font()". - -int fl_descent() - -\par -Recommended distance above the bottom of a \p %fl_height() tall box to draw -the text at so it looks centered vertically in that box. - -double fl_width(const char* txt) <br> -double fl_width(const char* txt, int n) <br> -double fl_width(unsigned int unicode_char) - -\par -Return the pixel width of a nul-terminated string, a sequence of \p n -characters, or a single character in the current font. - -const char* fl_shortcut_label(int shortcut) - -\par -Unparse a shortcut value as used by Fl_Button or Fl_Menu_Item -into a human-readable string like "Alt+N". This only -works if the shortcut is a character key or a numbered function -key. If the shortcut is zero an empty string is returned. The -return value points at a static buffer that is overwritten with -each call. - -\subsection ssect_Fonts Fonts - -FLTK supports a set of standard fonts based on the Times, -Helvetica/Arial, Courier, and Symbol typefaces, as well as -custom fonts that your application may load. Each font is -accessed by an index into a font table. - -Initially only the first 16 faces are filled in. There are -symbolic names for them: FL_HELVETICA, -FL_TIMES, FL_COURIER, and modifier values -FL_BOLD and FL_ITALIC which can be added to -these, and FL_SYMBOL and FL_ZAPF_DINGBATS. -Faces greater than 255 cannot be used in Fl_Widget -labels, since Fl_Widget stores the index as a byte. - -\anchor drawing_fl_font -void fl_font(int face, int size) - -\par -Set the current font, which is then used by the routines -described above. You may call this outside a draw context if -necessary to call fl_width(), but on X this will open -the display. - -\par -The font is identified by a \p face and a \p size. -The size of the font is measured in \p pixels and not "points". -Lines should be spaced \p size pixels apart or more. - -int fl_font() <br> -int fl_size() - -\par -Returns the face and size set by the most recent call to -\p fl_font(a,b). This can be used to save/restore the font. - -\subsection ssect_CharacterEncoding Character Encoding - -FLTK 1.3 expects all text in Unicode UTF-8 encoding. UTF-8 is -ASCII compatible for the first 128 characters. International -characters are encoded in multibyte sequences. - -FLTK expects individual characters, characters that are not part of -a string, in UCS-4 encoding, which is also ASCII compatible, but -requires 4 bytes to store a Unicode character. - -For more information about character encodings, see the chapter on -\ref unicode. - -\subsection ssect_Overlay Drawing Overlays - -These functions allow you to draw interactive selection rectangles -without using the overlay hardware. FLTK will XOR a single rectangle -outline over a window. - -void fl_overlay_rect(int x, int y, int w, int h); <br> -void fl_overlay_clear(); - -\par -\p %fl_overlay_rect() draws a selection rectangle, erasing any -previous rectangle by XOR'ing it first. \p %fl_overlay_clear() -will erase the rectangle without drawing a new one. - -\par -Using these functions is tricky. You should make a widget -with both a \p handle() and \p draw() method. -\p draw() should call \p %fl_overlay_clear() before -doing anything else. Your \p handle() method should call -<tt>window()->make_current()</tt> and then -\p %fl_overlay_rect() after FL_DRAG events, and -should call \p %fl_overlay_clear() after a -FL_RELEASE event. - - -\section drawing_images Drawing Images - -To draw images, you can either do it directly from data in -your memory, or you can create a Fl_Image object. The advantage of -drawing directly is that it is more intuitive, and it is faster -if the image data changes more often than it is redrawn. The -advantage of using the object is that FLTK will cache translated -forms of the image (on X it uses a server pixmap) and thus -redrawing is \e much faster. - -\subsection ssect_DirectImageDrawing Direct Image Drawing - -The behavior when drawing images when the current -transformation matrix is not the identity is not defined, so you -should only draw images when the matrix is set to the identity. - -\anchor drawing_fl_draw_image -void fl_draw_image(const uchar *buf,int X,int Y,int W,int H,int D,int L)<br> -void fl_draw_image_mono(const uchar *buf,int X,int Y,int W,int H,int D,int L) - -\par -Draw an 8-bit per color RGB or luminance image. The pointer -points at the "r" data of the top-left pixel. Color -data must be in <tt>r,g,b</tt> order. -The top left corner is given by \p X and \p Y -and the size of the image is given by \p W and \p H. -\p D is the delta to add to the pointer between pixels, -it may be any value greater or equal to \p 3, -or it can be negative to flip the image horizontally. -\p L is the delta to add to the pointer between lines -(if 0 is passed it uses \p W*D). -and may be larger than \p W*D to crop data, -or negative to flip the image vertically. - -\par -It is highly recommended that you put the following code before the -first show() of \e any window in your program to get rid -of the dithering if possible: - -\code -Fl::visual(FL_RGB); -\endcode - -\par -Gray scale (1-channel) images may be drawn. This is done if -<tt>abs(D)</tt> is less than 3, or by calling -\p %fl_draw_image_mono(). Only one 8-bit sample is used for -each pixel, and on screens with different numbers of bits for -red, green, and blue only gray colors are used. Setting -\p D greater than 1 will let you display one channel of a -color image. - -\par -\b Note: -The X version does not support all possible visuals. -If FLTK cannot draw the image in the current visual it -will abort. FLTK supports any visual of 8 bits or less, -and all common TrueColor visuals up to 32 bits. - -typedef void (*Fl_Draw_Image_Cb)(void *data,int x,int y,int w,uchar *buf) <br> -void fl_draw_image(Fl_Draw_Image_Cb cb,void *data,int X,int Y,int W,int H,int D) <br> -void fl_draw_image_mono(Fl_Draw_Image_Cb cb,void *data,int X,int Y,int W,int H,int D) - -\par -Call the passed function to provide each scan line of the -image. This lets you generate the image as it is being drawn, -or do arbitrary decompression of stored data, provided it can be -decompressed to individual scan lines easily. - -\par -The callback is called with the \p void* user data -pointer which can be used to point at a structure of information -about the image, and the \p x, \p y, and \p w -of the scan line desired from the image. 0,0 is the upper-left -corner of the image, <I>not <tt>X,Y</tt></I>. A pointer to a -buffer to put the data into is passed. You must copy \p w -pixels from scanline \p y, starting at pixel \p x, -to this buffer. - -\par -Due to cropping, less than the whole image may be requested. -So \p x may be greater than zero, the first \p y may -be greater than zero, and \p w may be less than \p W. -The buffer is long enough to store the entire \p W*D -pixels, this is for convenience with some decompression -schemes where you must decompress the entire line at once: -decompress it into the buffer, and then if \p x is not -zero, copy the data over so the \p x'th pixel is at the -start of the buffer. - -\par -You can assume the \p y's will be consecutive, except -the first one may be greater than zero. - -\par -If \p D is 4 or more, you must fill in the unused bytes -with zero. - -int fl_draw_pixmap(char* const* data, int x, int y, Fl_Color bg) <br> -int fl_draw_pixmap(const char* const* cdata, int x, int y, Fl_Color bg) - -\par -Draws XPM image data, with the top-left corner at the given position. -The image is dithered on 8-bit displays so you won't lose color space -for programs displaying both images and pixmaps. This function returns -zero if there was any error decoding the XPM data. - -\par -To use an XPM, do: - -\code -#include "foo.xpm" -... -fl_draw_pixmap(foo, X, Y); -\endcode - -\par -Transparent colors are replaced by the optional -Fl_Color argument. To draw with true transparency you must -use the Fl_Pixmap class. - -int fl_measure_pixmap(char* const* data, int &w, int &h) <br> -int fl_measure_pixmap(const char* const* cdata, int &w, int &h) - -\par -An XPM image contains the dimensions in its data. This -function finds and returns the width and height. The return -value is non-zero if the dimensions were parsed ok and zero if -there was any problem. - -\subsection ssect_DirectImageReading Direct Image Reading - -FLTK provides a single function for reading from the current -window or off-screen buffer into a RGB(A) image buffer. - -uchar* fl_read_image(uchar *p, int X, int Y, int W, int H, int alpha) - -\par -Read a RGB(A) image from the current window or off-screen -buffer. The \p p argument points to a buffer that can hold -the image and must be at least \p W*H*3 bytes when reading -RGB images and \p W*H*4 bytes when reading RGBA images. If -\p NULL, \p %fl_read_image() will create an array of -the proper size which can be freed using \p delete[]. - -\par -The \p alpha parameter controls whether an alpha -channel is created and the value that is placed in the alpha -channel. If 0, no alpha channel is generated. - -\subsection ssect_Fl_Image Image Classes - -FLTK provides a base image class called Fl_Image which supports -creating, copying, and drawing images of various kinds, along -with some basic color operations. Images can be used as labels -for widgets using the \p image() and \p deimage() methods or drawn directly. - -The Fl_Image class does almost nothing by itself, but is instead -supported by three basic image types: - -\li Fl_Bitmap -\li Fl_Pixmap -\li Fl_RGB_Image - -The Fl_Bitmap class encapsulates a mono-color bitmap image. -The \p draw() method draws the image using the current drawing -color. - -The Fl_Pixmap class encapsulates a colormapped image. -The \p draw() method draws the image using the colors in the -file, and masks off any transparent colors automatically. - -The Fl_RGB_Image class encapsulates a full-color -(or grayscale) image with 1 to 4 color components. Images with -an even number of components are assumed to contain an -alpha channel that is used for transparency. The transparency -provided by the draw() method is either a 24-bit -blend against the existing window contents or a "screen door" -transparency mask, depending on the platform and screen color depth. - -char fl_can_do_alpha_blending() - -\par -\p %fl_can_do_alpha_blending() will return 1, if your -platform supports true alpha blending for RGBA images, or 0, -if FLTK will use screen door transparency. - -FLTK also provides several image classes based on the three -standard image types for common file formats: - -\li Fl_GIF_Image -\li Fl_JPEG_Image -\li Fl_PNG_Image -\li Fl_PNM_Image -\li Fl_XBM_Image -\li Fl_XPM_Image - -Each of these image classes load a named file of the -corresponding format. The Fl_Shared_Image class -can be used to load any type of image file - the class examines -the file and constructs an image of the appropriate type. - -Finally, FLTK provides a special image class called Fl_Tiled_Image to -tile another image object in the specified area. This class can be -used to tile a background image in a Fl_Group widget, for example. - -virtual void Fl_Tiled_Image::copy(); <br> -virtual Fl_Image* Fl_Tiled_Image::copy(int w, int h); - -\par -The \p copy() method creates a copy of the image. The second form -specifies the new size of the image - the image is resized using the -nearest-neighbor algorithm. - -void Fl_Tiled_Image::draw(int x, int y, int w, int h, int ox, int oy); - -\par -The \p draw() method draws the image object. -<tt>x,y,w,h</tt> indicates a destination rectangle. -<tt>ox,oy,w,h</tt> is a source rectangle. This source rectangle -is copied to the destination. The source rectangle may extend -outside the image, i.e. \p ox and \p oy may be -negative and \p w and \p h may be bigger than the -image, and this area is left unchanged. - -void Fl_Tiled_Image::draw(int x, int y) - -\par -Draws the image with the upper-left corner at <tt>x,y</tt>. -This is the same as doing \p draw(x,y,img->w(),img->h(),0,0). - -\subsection ssect_Offscreen Offscreen Drawing - -Sometimes it can be very useful to generate a complex drawing -in memory first and copy it to the screen at a later point in -time. This technique can significantly reduce the amount of -repeated drawing. Offscreen drawing functions are declared in <FL/x.H>. -Fl_Double_Window uses offscreen rendering -to avoid flickering on systems that don't support -double-buffering natively. - -Fl_Offscreen fl_create_offscreen(int w, int h) - -\par -Create an RGB offscreen buffer with \p w*h pixels. - -void fl_delete_offscreen(Fl_Offscreen) - -\par -Delete a previously created offscreen buffer. All drawings are lost. - -void fl_begin_offscreen(Fl_Offscreen) - -\par -Send all subsequent drawing commands to this offscreen buffer. -FLTK can draw into a buffer at any time. There is no need to wait for -an Fl_Widget::draw() to occur. - -void fl_end_offscreen() - -\par -Quit sending drawing commands to this offscreen buffer. - -void fl_copy_offscreen(int x, int y, int w, int h, Fl_Offscreen osrc, int srcx, int srcy) - -\par -Copy a rectangular area of the size \p w*h from \p srcx,srcy -in the offscreen buffer into the current buffer at \p x,y. - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="editor.html"> - [Prev] - Designing a Simple Text Editor - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="events.html"> - Handling Events - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/editor-replace.png b/branch-3.0-2011/documentation/src/editor-replace.png Binary files differdeleted file mode 100644 index a371b18a5..000000000 --- a/branch-3.0-2011/documentation/src/editor-replace.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/editor.dox b/branch-3.0-2011/documentation/src/editor.dox deleted file mode 100644 index 490ee17d0..000000000 --- a/branch-3.0-2011/documentation/src/editor.dox +++ /dev/null @@ -1,918 +0,0 @@ -/** - - \page editor Designing a Simple Text Editor - -This chapter takes you through the design of a simple -FLTK-based text editor. - -\section editor_goals Determining the Goals of the Text Editor - -Since this will be the first big project you'll be doing with FLTK, -lets define what we want our text editor to do: - --# Provide a menubar/menus for all functions. --# Edit a single text file, possibly with multiple views. --# Load from a file. --# Save to a file. --# Cut/copy/delete/paste functions. --# Search and replace functions. --# Keep track of when the file has been changed. - -<!-- NEED 4in --> - -\section editor_main_window Designing the Main Window - -Now that we've outlined the goals for our editor, we can begin with -the design of our GUI. Obviously the first thing that we need is a -window, which we'll place inside a class called \p EditorWindow: - -\code -class EditorWindow : public Fl_Double_Window { - public: - EditorWindow(int w, int h, const char* t); - ~EditorWindow(); - - Fl_Window *replace_dlg; - Fl_Input *replace_find; - Fl_Input *replace_with; - Fl_Button *replace_all; - Fl_Return_Button *replace_next; - Fl_Button *replace_cancel; - - Fl_Text_Editor *editor; - char search[256]; -}; -\endcode - -\section editor_variables Variables - -Our text editor will need some global variables to keep track of things: - -\code -int changed = 0; -char filename[256] = ""; -Fl_Text_Buffer *textbuf; -\endcode - -The \p textbuf variable is the text editor buffer for -our window class described previously. We'll cover the other -variables as we build the application. - -\section editor_menubars Menubars and Menus - -The first goal requires us to use a menubar and menus that -define each function the editor needs to perform. The Fl_Menu_Item -structure is used to define the menus and items in a menubar: - -\code -Fl_Menu_Item menuitems[] = { - { "&File", 0, 0, 0, FL_SUBMENU }, - { "&New File", 0, (Fl_Callback *)new_cb }, - { "&Open File...", FL_COMMAND + 'o', (Fl_Callback *)open_cb }, - { "&Insert File...", FL_COMMAND + 'i', (Fl_Callback *)insert_cb, 0, FL_MENU_DIVIDER }, - { "&Save File", FL_COMMAND + 's', (Fl_Callback *)save_cb }, - { "Save File &As...", FL_COMMAND + FL_SHIFT + 's', (Fl_Callback *)saveas_cb, 0, FL_MENU_DIVIDER }, - { "New &View", FL_ALT + 'v', (Fl_Callback *)view_cb, 0 }, - { "&Close View", FL_COMMAND + 'w', (Fl_Callback *)close_cb, 0, FL_MENU_DIVIDER }, - { "E&xit", FL_COMMAND + 'q', (Fl_Callback *)quit_cb, 0 }, - { 0 }, - - { "&Edit", 0, 0, 0, FL_SUBMENU }, - { "&Undo", FL_COMMAND + 'z', (Fl_Callback *)undo_cb, 0, FL_MENU_DIVIDER }, - { "Cu&t", FL_COMMAND + 'x', (Fl_Callback *)cut_cb }, - { "&Copy", FL_COMMAND + 'c', (Fl_Callback *)copy_cb }, - { "&Paste", FL_COMMAND + 'v', (Fl_Callback *)paste_cb }, - { "&Delete", 0, (Fl_Callback *)delete_cb }, - { 0 }, - - { "&Search", 0, 0, 0, FL_SUBMENU }, - { "&Find...", FL_COMMAND + 'f', (Fl_Callback *)find_cb }, - { "F&ind Again", FL_COMMAND + 'g', find2_cb }, - { "&Replace...", FL_COMMAND + 'r', replace_cb }, - { "Re&place Again", FL_COMMAND + 't', replace2_cb }, - { 0 }, - - { 0 } -}; -\endcode - -Once we have the menus defined we can create the -Fl_Menu_Bar widget and assign the menus to it with: - -\code -Fl_Menu_Bar *m = new Fl_Menu_Bar(0, 0, 640, 30); -m->copy(menuitems); -\endcode - -We'll define the callback functions later. - -\section editor_editing Editing the Text - -To keep things simple our text editor will use the -Fl_Text_Editor widget to edit the text: - -\code -w->editor = new Fl_Text_Editor(0, 30, 640, 370); -w->editor->buffer(textbuf); -\endcode - -So that we can keep track of changes to the file, we also want to add -a "modify" callback: - -\code -textbuf->add_modify_callback(changed_cb, w); -textbuf->call_modify_callbacks(); -\endcode - -Finally, we want to use a mono-spaced font like \p FL_COURIER: - -\code -w->editor->textfont(FL_COURIER); -\endcode - -\section editor_replace_dialog The Replace Dialog - -We can use the FLTK convenience functions for many of the -editor's dialogs, however the replace dialog needs its own -custom window. To keep things simple we will have a -"find" string, a "replace" string, and -"replace all", "replace next", and -"cancel" buttons. The strings are just -Fl_Input widgets, the "replace all" and -"cancel" buttons are Fl_Button widgets, and -the "replace next " button is a -Fl_Return_Button widget: - -\image html editor-replace.png "Figure 4-1: The search and replace dialog" -\image latex editor-replace.png "The search and replace dialog" width=10cm - -\code -Fl_Window *replace_dlg = new Fl_Window(300, 105, "Replace"); -Fl_Input *replace_find = new Fl_Input(70, 10, 200, 25, "Find:"); -Fl_Input *replace_with = new Fl_Input(70, 40, 200, 25, "Replace:"); -Fl_Button *replace_all = new Fl_Button(10, 70, 90, 25, "Replace All"); -Fl_Button *replace_next = new Fl_Button(105, 70, 120, 25, "Replace Next"); -Fl_Button *replace_cancel = new Fl_Button(230, 70, 60, 25, "Cancel"); -\endcode - -\section editor_callbacks Callbacks - -Now that we've defined the GUI components of our editor, we -need to define our callback functions. - -\subsection editor_changed_cb changed_cb() - -This function will be called whenever the user changes any text in the -\p editor widget: - -\code -void changed_cb(int, int nInserted, int nDeleted,int, const char*, void* v) { - if ((nInserted || nDeleted) && !loading) changed = 1; - EditorWindow *w = (EditorWindow *)v; - set_title(w); - if (loading) w->editor->show_insert_position(); -} -\endcode - -The \p set_title() function is one that we will write to set -the changed status on the current file. We're doing it this way -because we want to show the changed status in the window's -title bar. - -\subsection editor_copy_cb copy_cb() - -This callback function will call Fl_Text_Editor::kf_copy() -to copy the currently selected text to the clipboard: - -\code -void copy_cb(Fl_Widget*, void* v) { - EditorWindow* e = (EditorWindow*)v; - Fl_Text_Editor::kf_copy(0, e->editor); -} -\endcode - -\subsection editor_cut_cb cut_cb() - -This callback function will call Fl_Text_Editor::kf_cut() -to cut the currently selected text to the clipboard: - -\code -void cut_cb(Fl_Widget*, void* v) { - EditorWindow* e = (EditorWindow*)v; - Fl_Text_Editor::kf_cut(0, e->editor); -} -\endcode - -\subsection editor_delete_cb delete_cb() - -This callback function will call Fl_Text_Buffer::remove_selection() -to delete the currently selected text to the clipboard: - -\code -void delete_cb(Fl_Widget*, void* v) { - textbuf->remove_selection(); -} -\endcode - -\subsection editor_find_cb find_cb() - -This callback function asks for a search string using the -fl_input() convenience function and then calls the \p find2_cb() -function to find the string: - -\code -void find_cb(Fl_Widget* w, void* v) { - EditorWindow* e = (EditorWindow*)v; - const char *val; - - val = fl_input("Search String:", e->search); - if (val != NULL) { - // User entered a string - go find it! - strcpy(e->search, val); - find2_cb(w, v); - } -\endcode - -\subsection editor_find2_cb find2_cb() - -This function will find the next occurrence of the search -string. If the search string is blank then we want to pop up the -search dialog: - -\code -void find2_cb(Fl_Widget* w, void* v) { - EditorWindow* e = (EditorWindow*)v; - if (e->search[0] == '\0') { - // Search string is blank; get a new one... - find_cb(w, v); - return; - } - - int pos = e->editor->insert_position(); - int found = textbuf->search_forward(pos, e->search, &pos); - if (found) { - // Found a match; select and update the position... - textbuf->select(pos, pos+strlen(e->search)); - e->editor->insert_position(pos+strlen(e->search)); - e->editor->show_insert_position(); - } - else fl_alert("No occurrences of \'%s\' found!", e->search); -} -\endcode - -If the search string cannot be found we use the fl_alert() -convenience function to display a message to that effect. - -\subsection editor_new_cb new_cb() - -This callback function will clear the editor widget and current -filename. It also calls the \p check_save() function to give the -user the opportunity to save the current file first as needed: - -\code -void new_cb(Fl_Widget*, void*) { - if (!check_save()) return; - - filename[0] = '\0'; - textbuf->select(0, textbuf->length()); - textbuf->remove_selection(); - changed = 0; - textbuf->call_modify_callbacks(); -} -\endcode - -\subsection editor_open_cb open_cb() - -This callback function will ask the user for a filename and then load -the specified file into the input widget and current filename. It also -calls the \p check_save() function to give the user the -opportunity to save the current file first as needed: - -\code -void open_cb(Fl_Widget*, void*) { - if (!check_save()) return; - - char *newfile = fl_file_chooser("Open File?", "*", filename); - if (newfile != NULL) load_file(newfile, -1); -} -\endcode - -We call the \p load_file() function to actually load the file. - -\subsection editor_paste_cb paste_cb() - -This callback function will call Fl_Text_Editor::kf_paste() -to paste the clipboard at the current position: - -\code -void paste_cb(Fl_Widget*, void* v) { - EditorWindow* e = (EditorWindow*)v; - Fl_Text_Editor::kf_paste(0, e->editor); -} -\endcode - -\subsection editor_quit_cb quit_cb() - -The quit callback will first see if the current file has been -modified, and if so give the user a chance to save it. It then exits -from the program: - -\code -void quit_cb(Fl_Widget*, void*) { - if (changed && !check_save()) - return; - - exit(0); -} -\endcode - -\subsection editor_replace_cb replace_cb() - -The replace callback just shows the replace dialog: - -\code -void replace_cb(Fl_Widget*, void* v) { - EditorWindow* e = (EditorWindow*)v; - e->replace_dlg->show(); -} -\endcode - -\subsection editor_replace2_cb replace2_cb() - -This callback will replace the next occurrence of the replacement -string. If nothing has been entered for the replacement string, then -the replace dialog is displayed instead: - -\code -void replace2_cb(Fl_Widget*, void* v) { - EditorWindow* e = (EditorWindow*)v; - const char *find = e->replace_find->value(); - const char *replace = e->replace_with->value(); - - if (find[0] == '\0') { - // Search string is blank; get a new one... - e->replace_dlg->show(); - return; - } - - e->replace_dlg->hide(); - - int pos = e->editor->insert_position(); - int found = textbuf->search_forward(pos, find, &pos); - - if (found) { - // Found a match; update the position and replace text... - textbuf->select(pos, pos+strlen(find)); - textbuf->remove_selection(); - textbuf->insert(pos, replace); - textbuf->select(pos, pos+strlen(replace)); - e->editor->insert_position(pos+strlen(replace)); - e->editor->show_insert_position(); - } - else fl_alert("No occurrences of \'%s\' found!", find); -} -\endcode - -\subsection editor_replall_cb replall_cb() - -This callback will replace all occurrences of the search -string in the file: - -\code -void replall_cb(Fl_Widget*, void* v) { - EditorWindow* e = (EditorWindow*)v; - const char *find = e->replace_find->value(); - const char *replace = e->replace_with->value(); - - find = e->replace_find->value(); - if (find[0] == '\0') { - // Search string is blank; get a new one... - e->replace_dlg->show(); - return; - } - - e->replace_dlg->hide(); - - e->editor->insert_position(0); - int times = 0; - - // Loop through the whole string - for (int found = 1; found;) { - int pos = e->editor->insert_position(); - found = textbuf->search_forward(pos, find, &pos); - - if (found) { - // Found a match; update the position and replace text... - textbuf->select(pos, pos+strlen(find)); - textbuf->remove_selection(); - textbuf->insert(pos, replace); - e->editor->insert_position(pos+strlen(replace)); - e->editor->show_insert_position(); - times++; - } - } - - if (times) fl_message("Replaced %d occurrences.", times); - else fl_alert("No occurrences of \'%s\' found!", find); -} -\endcode - -\subsection editor_replcan_cb replcan_cb() - -This callback just hides the replace dialog: - -\code -void replcan_cb(Fl_Widget*, void* v) { - EditorWindow* e = (EditorWindow*)v; - e->replace_dlg->hide(); -} -\endcode - -\subsection editor_save_cb save_cb() - -This callback saves the current file. If the current filename is -blank it calls the "save as" callback: - -\code -void save_cb(void) { - if (filename[0] == '\0') { - // No filename - get one! - saveas_cb(); - return; - } - else save_file(filename); -} -\endcode - -The \p save_file() function saves the current file to the -specified filename. - -\subsection editor_saveas_cb saveas_cb() - -This callback asks the user for a filename and saves the current file: - -\code -void saveas_cb(void) { - char *newfile; - - newfile = fl_file_chooser("Save File As?", "*", filename); - if (newfile != NULL) save_file(newfile); -} -\endcode - -The \p save_file() function saves the current file to the -specified filename. - -\section editor_other_functions Other Functions - -Now that we've defined the callback functions, we need our support -functions to make it all work: - -\subsection editor_check_save check_save() - -This function checks to see if the current file needs to be saved. If -so, it asks the user if they want to save it: - -\code -int check_save(void) { - if (!changed) return 1; - - int r = fl_choice("The current file has not been saved.\n" - "Would you like to save it now?", - "Cancel", "Save", "Discard"); - - if (r == 1) { - save_cb(); // Save the file... - return !changed; - } - - return (r == 2) ? 1 : 0; -} -\endcode - -\subsection editor_load_file load_file() - -This function loads the specified file into the \p textbuf variable: - -\code -int loading = 0; -void load_file(char *newfile, int ipos) { - loading = 1; - int insert = (ipos != -1); - changed = insert; - if (!insert) strcpy(filename, ""); - int r; - if (!insert) r = textbuf->loadfile(newfile); - else r = textbuf->insertfile(newfile, ipos); - if (r) - fl_alert("Error reading from file \'%s\':\n%s.", newfile, strerror(errno)); - else - if (!insert) strcpy(filename, newfile); - loading = 0; - textbuf->call_modify_callbacks(); -} -\endcode - -When loading the file we use the Fl_Text_Buffer::loadfile() -method to "replace" the text in the buffer, or the -Fl_Text_Buffer::insertfile() -method to insert text in the buffer from the named file. - -\subsection editor_save_file save_file() - -This function saves the current buffer to the specified file: - -\code -void save_file(char *newfile) { - if (textbuf->savefile(newfile)) - fl_alert("Error writing to file \'%s\':\n%s.", newfile, strerror(errno)); - else - strcpy(filename, newfile); - changed = 0; - textbuf->call_modify_callbacks(); -} -\endcode - -\subsection editor_set_title set_title() - -This function checks the \p changed variable and updates the -window label accordingly: -\code -void set_title(Fl_Window* w) { - if (filename[0] == '\0') strcpy(title, "Untitled"); - else { - char *slash; - slash = strrchr(filename, '/'); -#ifdef WIN32 - if (slash == NULL) slash = strrchr(filename, '\\'); -#endif - if (slash != NULL) strcpy(title, slash + 1); - else strcpy(title, filename); - } - - if (changed) strcat(title, " (modified)"); - - w->label(title); -} -\endcode - -\section editor_main_function The main() Function - -Once we've created all of the support functions, the only thing left -is to tie them all together with the \p main() function. -The \p main() function creates a new text buffer, creates a -new view (window) for the text, shows the window, loads the file on -the command-line (if any), and then enters the FLTK event loop: - -\code -int main(int argc, char **argv) { - textbuf = new Fl_Text_Buffer; - - Fl_Window* window = new_view(); - - window->show(1, argv); - - if (argc > 1) load_file(argv[1], -1); - - return Fl::run(); -} -\endcode - -\section editor_compiling Compiling the Editor - -The complete source for our text editor can be found in the -\p test/editor.cxx source file. Both the Makefile and Visual C++ -workspace include the necessary rules to build the editor. You can -also compile it using a standard compiler with: - -\code -CC -o editor editor.cxx -lfltk -lXext -lX11 -lm -\endcode - -or by using the \p fltk-config script with: - -\code -fltk-config --compile editor.cxx -\endcode - -As noted in \ref basics_standard_compiler, you may need to -include compiler and linker options to tell them where to find the FLTK -library. Also, the \p CC command may also be called \p gcc -or \p c++ on your system. - -Congratulations, you've just built your own text editor! - -\section editor_final_product The Final Product - -The final editor window should look like the image in Figure 4-2. - -\image html editor.png "Figure 4-2: The completed editor window" -\image latex editor.png "The completed editor window" width=12cm - -\section editor_advanced_features Advanced Features - -Now that we've implemented the basic functionality, it is -time to show off some of the advanced features of the -Fl_Text_Editor widget. - -\subsection editor_syntax Syntax Highlighting - -The Fl_Text_Editor widget supports highlighting -of text with different fonts, colors, and sizes. The -implementation is based on the excellent -<A HREF="http://www.nedit.org/">NEdit</A> -text editor core, from http://www.nedit.org/, which -uses a parallel "style" buffer which tracks the font, color, and -size of the text that is drawn. - -Styles are defined using the -Fl_Text_Display::Style_Table_Entry structure -defined in <tt><FL/Fl_Text_Display.H></tt>: - -\code -struct Style_Table_Entry { - Fl_Color color; - Fl_Font font; - int size; - unsigned attr; -}; -\endcode - -The \p color member sets the color for the text, -the \p font member sets the FLTK font index to use, -and the \p size member sets the pixel size of the -text. The \p attr member is currently not used. - -For our text editor we'll define 7 styles for plain code, -comments, keywords, and preprocessor directives: - -\code -Fl_Text_Display::Style_Table_Entry styletable[] = { // Style table - { FL_BLACK, FL_COURIER, FL_NORMAL_SIZE }, // A - Plain - { FL_DARK_GREEN, FL_COURIER_ITALIC, FL_NORMAL_SIZE }, // B - Line comments - { FL_DARK_GREEN, FL_COURIER_ITALIC, FL_NORMAL_SIZE }, // C - Block comments - { FL_BLUE, FL_COURIER, FL_NORMAL_SIZE }, // D - Strings - { FL_DARK_RED, FL_COURIER, FL_NORMAL_SIZE }, // E - Directives - { FL_DARK_RED, FL_COURIER_BOLD, FL_NORMAL_SIZE }, // F - Types - { FL_BLUE, FL_COURIER_BOLD, FL_NORMAL_SIZE } // G - Keywords -}; -\endcode - -You'll notice that the comments show a letter next to each -style - each style in the style buffer is referenced using a -character starting with the letter 'A'. - -You call the \p highlight_data() method to associate the -style data and buffer with the text editor widget: - -\code -Fl_Text_Buffer *stylebuf; - -w->editor->highlight_data(stylebuf, styletable, - sizeof(styletable) / sizeof(styletable[0]), - 'A', style_unfinished_cb, 0); -\endcode - -Finally, you need to add a callback to the main text buffer so -that changes to the text buffer are mirrored in the style buffer: - -\code -textbuf->add_modify_callback(style_update, w->editor); -\endcode - -The \p style_update() function, like the \p change_cb() -function described earlier, is called whenever text is added or removed from -the text buffer. It mirrors the changes in the style buffer and then updates -the style data as necessary: - -\code -// -// 'style_update()' - Update the style buffer... -// - -void -style_update(int pos, // I - Position of update - int nInserted, // I - Number of inserted chars - int nDeleted, // I - Number of deleted chars - int nRestyled, // I - Number of restyled chars - const char *deletedText, // I - Text that was deleted - void *cbArg) { // I - Callback data - int start, // Start of text - end; // End of text - char last, // Last style on line - *style, // Style data - *text; // Text data - - - // If this is just a selection change, just unselect the style buffer... - if (nInserted == 0 && nDeleted == 0) { - stylebuf->unselect(); - return; - } - - // Track changes in the text buffer... - if (nInserted > 0) { - // Insert characters into the style buffer... - style = new char[nInserted + 1]; - memset(style, 'A', nInserted); - style[nInserted] = '\0'; - - stylebuf->replace(pos, pos + nDeleted, style); - delete[] style; - } else { - // Just delete characters in the style buffer... - stylebuf->remove(pos, pos + nDeleted); - } - - // Select the area that was just updated to avoid unnecessary - // callbacks... - stylebuf->select(pos, pos + nInserted - nDeleted); - - // Re-parse the changed region; we do this by parsing from the - // beginning of the line of the changed region to the end of - // the line of the changed region... Then we check the last - // style character and keep updating if we have a multi-line - // comment character... - start = textbuf->line_start(pos); - end = textbuf->line_end(pos + nInserted - nDeleted); - text = textbuf->text_range(start, end); - style = stylebuf->text_range(start, end); - last = style[end - start - 1]; - - style_parse(text, style, end - start); - - stylebuf->replace(start, end, style); - ((Fl_Text_Editor *)cbArg)->redisplay_range(start, end); - - if (last != style[end - start - 1]) { - // The last character on the line changed styles, so reparse the - // remainder of the buffer... - free(text); - free(style); - - end = textbuf->length(); - text = textbuf->text_range(start, end); - style = stylebuf->text_range(start, end); - - style_parse(text, style, end - start); - - stylebuf->replace(start, end, style); - ((Fl_Text_Editor *)cbArg)->redisplay_range(start, end); - } - - free(text); - free(style); -} -\endcode - -The \p style_parse() function scans a copy of the -text in the buffer and generates the necessary style characters -for display. It assumes that parsing begins at the start of a line: - -\code -// -// 'style_parse()' - Parse text and produce style data. -// - -void -style_parse(const char *text, - char *style, - int length) { - char current; - int col; - int last; - char buf[255], - *bufptr; - const char *temp; - - for (current = *style, col = 0, last = 0; length > 0; length --, text ++) { - if (current == 'A') { - // Check for directives, comments, strings, and keywords... - if (col == 0 && *text == '#') { - // Set style to directive - current = 'E'; - } else if (strncmp(text, "//", 2) == 0) { - current = 'B'; - } else if (strncmp(text, "/*", 2) == 0) { - current = 'C'; - } else if (strncmp(text, "\\\"", 2) == 0) { - // Quoted quote... - *style++ = current; - *style++ = current; - text ++; - length --; - col += 2; - continue; - } else if (*text == '\"') { - current = 'D'; - } else if (!last && islower(*text)) { - // Might be a keyword... - for (temp = text, bufptr = buf; - islower(*temp) && bufptr < (buf + sizeof(buf) - 1); - *bufptr++ = *temp++); - - if (!islower(*temp)) { - *bufptr = '\0'; - - bufptr = buf; - - if (bsearch(&bufptr, code_types, - sizeof(code_types) / sizeof(code_types[0]), - sizeof(code_types[0]), compare_keywords)) { - while (text < temp) { - *style++ = 'F'; - text ++; - length --; - col ++; - } - - text --; - length ++; - last = 1; - continue; - } else if (bsearch(&bufptr, code_keywords, - sizeof(code_keywords) / sizeof(code_keywords[0]), - sizeof(code_keywords[0]), compare_keywords)) { - while (text < temp) { - *style++ = 'G'; - text ++; - length --; - col ++; - } - - text --; - length ++; - last = 1; - continue; - } - } - } - } else if (current == 'C' && strncmp(text, "*/", 2) == 0) { - // Close a C comment... - *style++ = current; - *style++ = current; - text ++; - length --; - current = 'A'; - col += 2; - continue; - } else if (current == 'D') { - // Continuing in string... - if (strncmp(text, "\\\"", 2) == 0) { - // Quoted end quote... - *style++ = current; - *style++ = current; - text ++; - length --; - col += 2; - continue; - } else if (*text == '\"') { - // End quote... - *style++ = current; - col ++; - current = 'A'; - continue; - } - } - - // Copy style info... - if (current == 'A' && (*text == '{' || *text == '}')) *style++ = 'G'; - else *style++ = current; - col ++; - - last = isalnum(*text) || *text == '.'; - - if (*text == '\n') { - // Reset column and possibly reset the style - col = 0; - if (current == 'B' || current == 'E') current = 'A'; - } - } -} -\endcode - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="common.html"> - [Prev] - Common Widgets and Attributes - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="drawing.html"> - Drawing Things in FLTK - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/editor.png b/branch-3.0-2011/documentation/src/editor.png Binary files differdeleted file mode 100644 index 4e3c2347d..000000000 --- a/branch-3.0-2011/documentation/src/editor.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/enumerations.dox b/branch-3.0-2011/documentation/src/enumerations.dox deleted file mode 100644 index 51c0a149c..000000000 --- a/branch-3.0-2011/documentation/src/enumerations.dox +++ /dev/null @@ -1,336 +0,0 @@ -/** - - \page enumerations FLTK Enumerations - - \note This file is not actively maintained any more, but is left - here as a reference, until the doxygen documentation is - completed. - - \sa \ref FL/Enumerations.H. - -This appendix lists the enumerations provided in the -<FL/Enumerations.H> header file, organized by section. -Constants whose value are zero are marked with "(0)", -this is often useful to know when programming. - - -\section enumerations_versions Version Numbers - -The FLTK version number is stored in a number of compile-time constants: - -\li FL_MAJOR_VERSION - The major release number, currently 1. -\li FL_MINOR_VERSION - The minor release number, currently 3. -\li FL_PATCH_VERSION - The patch release number, currently 0. -\li FL_VERSION - A combined floating-point version number for - the major, minor, and patch release numbers, currently 1.0300. - - -\section enumerations_events Events - -Events are identified by an \p Fl_Event enumeration value. The -following events are currently defined: - -\li FL_NO_EVENT - No event (or an event fltk does not - understand) occurred (0). -\li FL_PUSH - A mouse button was pushed. -\li FL_RELEASE - A mouse button was released. -\li FL_ENTER - The mouse pointer entered a widget. -\li FL_LEAVE - The mouse pointer left a widget. -\li FL_DRAG - The mouse pointer was moved with a button pressed. -\li FL_FOCUS - A widget should receive keyboard focus. -\li FL_UNFOCUS - A widget loses keyboard focus. -\li FL_KEYBOARD - A key was pressed. -\li FL_CLOSE - A window was closed. -\li FL_MOVE - The mouse pointer was moved with no buttons pressed. -\li FL_SHORTCUT - The user pressed a shortcut key. -\li FL_DEACTIVATE - The widget has been deactivated. -\li FL_ACTIVATE - The widget has been activated. -\li FL_HIDE - The widget has been hidden. -\li FL_SHOW - The widget has been shown. -\li FL_PASTE - The widget should paste the contents of the - clipboard. -\li FL_SELECTIONCLEAR - The widget should clear any selections - made for the clipboard. -\li FL_MOUSEWHEEL - The horizontal or vertical mousewheel was turned. -\li FL_DND_ENTER - The mouse pointer entered a widget dragging data. -\li FL_DND_DRAG - The mouse pointer was moved dragging data. -\li FL_DND_LEAVE - The mouse pointer left a widget still dragging - data. -\li FL_DND_RELEASE - Dragged data is about to be dropped. - - -\section enumerations_when Callback "When" Conditions - -The following constants determine when a callback is performed: - -\li FL_WHEN_NEVER - Never call the callback (0). -\li FL_WHEN_CHANGED - Do the callback only when the widget - value changes. -\li FL_WHEN_NOT_CHANGED - Do the callback whenever the user - interacts with the widget. -\li FL_WHEN_RELEASE - Do the callback when the button or key - is released and the value changes. -\li FL_WHEN_ENTER_KEY - Do the callback when the user presses - the ENTER key and the value changes. -\li FL_WHEN_RELEASE_ALWAYS - Do the callback when the button - or key is released, even if the value doesn't change. -\li FL_WHEN_ENTER_KEY_ALWAYS - Do the callback when the user - presses the ENTER key, even if the value doesn't change. - - -\section enumeration_button_values Fl::event_button() Values - -The following constants define the button numbers for FL_PUSH and -FL_RELEASE events: - -\li FL_LEFT_MOUSE - the left mouse button -\li FL_MIDDLE_MOUSE - the middle mouse button -\li FL_RIGHT_MOUSE - the right mouse button - - -\section enumerations_event_key Fl::event_key() Values - -The following constants define the non-ASCII keys on the keyboard for -FL_KEYBOARD and FL_SHORTCUT events: - -\li FL_Button - A mouse button; use <tt>Fl_Button + n</tt> - for mouse button <tt>n</tt>. -\li FL_BackSpace - The backspace key. -\li FL_Tab - The tab key. -\li FL_Enter - The enter key. -\li FL_Pause - The pause key. -\li FL_Scroll_Lock - The scroll lock key. -\li FL_Escape - The escape key. -\li FL_Home - The home key. -\li FL_Left - The left arrow key. -\li FL_Up - The up arrow key. -\li FL_Right - The right arrow key. -\li FL_Down - The down arrow key. -\li FL_Page_Up - The page-up key. -\li FL_Page_Down - The page-down key. -\li FL_End - The end key. -\li FL_Print - The print (or print-screen) key. -\li FL_Insert - The insert key. -\li FL_Menu - The menu key. -\li FL_Num_Lock - The num lock key. -\li FL_KP - One of the keypad numbers; use <tt>FL_KP + n</tt> - for number <tt>n</tt>. -\li FL_KP_Enter - The enter key on the keypad. -\li FL_F - One of the function keys; use <tt>FL_F + n</tt> - for function key <tt>n</tt>. -\li FL_Shift_L - The lefthand shift key. -\li FL_Shift_R - The righthand shift key. -\li FL_Control_L - The lefthand control key. -\li FL_Control_R - The righthand control key. -\li FL_Caps_Lock - The caps lock key. -\li FL_Meta_L - The left meta/Windows key. -\li FL_Meta_R - The right meta/Windows key. -\li FL_Alt_L - The left alt key. -\li FL_Alt_R - The right alt key. -\li FL_Delete - The delete key. - - -\section enumerations_event_state Fl::event_state() Values - -The following constants define bits in the Fl::event_state() -value: - -\li FL_SHIFT - One of the shift keys is down. -\li FL_CAPS_LOCK - The caps lock is on. -\li FL_CTRL - One of the ctrl keys is down. -\li FL_ALT - One of the alt keys is down. -\li FL_NUM_LOCK - The num lock is on. -\li FL_META - One of the meta/Windows keys is down. -\li FL_COMMAND - An alias for FL_CTRL on WIN32 and X11, - or FL_META on MacOS X. -\li FL_SCROLL_LOCK - The scroll lock is on. -\li FL_BUTTON1 - Mouse button 1 is pushed. -\li FL_BUTTON2 - Mouse button 2 is pushed. -\li FL_BUTTON3 - Mouse button 3 is pushed. -\li FL_BUTTONS - Any mouse button is pushed. -\li FL_BUTTON(n) - Mouse button \p n ( where <tt>n > 0</tt>) is pushed. - -<!-- NEED 4in --> - - -\section enumerations_alignment Alignment Values - -The following constants define bits that can be used with -Fl_Widget::alighn() -to control the positioning of the label: - -\li FL_ALIGN_CENTER - The label is centered (0). -\li FL_ALIGN_TOP - The label is top-aligned. -\li FL_ALIGN_BOTTOM - The label is bottom-aligned. -\li FL_ALIGN_LEFT - The label is left-aligned. -\li FL_ALIGN_RIGHT - The label is right-aligned. -\li FL_ALIGN_CLIP - The label is clipped to the widget. -\li FL_ALIGN_WRAP - The label text is wrapped as needed. -\li FL_ALIGN_TOP_LEFT - The label appears at the top of the widget, aligned to the left. -\li FL_ALIGN_TOP_RIGHT - The label appears at the top of the widget, aligned to the right. -\li FL_ALIGN_BOTTOM_LEFT - The label appears at the bottom of the widget, aligned to the left. -\li FL_ALIGN_BOTTOM_RIGHT - The label appears at the bottom of the widget, aligned to the right. -\li FL_ALIGN_LEFT_TOP - The label appears to the left of the widget, aligned at the top. Outside labels only. -\li FL_ALIGN_RIGHT_TOP - The label appears to the right of the widget, aligned at the top. Outside labels only. -\li FL_ALIGN_LEFT_BOTTOM - The label appears to the left of the widget, aligned at the bottom. Outside labels only. -\li FL_ALIGN_RIGHT_BOTTOM - The label appears to the right of the widget, aligned at the bottom. Outside labels only. -\li FL_ALIGN_INSIDE - 'or' this with other values to put label inside the widget. -\li FL_ALIGN_TEXT_OVER_IMAGE - Label text will appear above the image. -\li FL_ALIGN_IMAGE_OVER_TEXT - Label text will be below the image. -\li FL_ALIGN_IMAGE_NEXT_TO_TEXT - The image will appear to the left of the text. -\li FL_ALIGN_TEXT_NEXT_TO_IMAGE - The image will appear to the right of the text. -\li FL_ALIGN_IMAGE_BACKDROP - The image will be used as a background for the widget. - -\section enumerations_fonts Fonts - -The following constants define the standard FLTK fonts: - -\li FL_HELVETICA - Helvetica (or Arial) normal (0). -\li FL_HELVETICA_BOLD - Helvetica (or Arial) bold. -\li FL_HELVETICA_ITALIC - Helvetica (or Arial) oblique. -\li FL_HELVETICA_BOLD_ITALIC - Helvetica (or Arial) bold-oblique. -\li FL_COURIER - Courier normal. -\li FL_COURIER_BOLD - Courier bold. -\li FL_COURIER_ITALIC - Courier italic. -\li FL_COURIER_BOLD_ITALIC - Courier bold-italic. -\li FL_TIMES - Times roman. -\li FL_TIMES_BOLD - Times bold. -\li FL_TIMES_ITALIC - Times italic. -\li FL_TIMES_BOLD_ITALIC - Times bold-italic. -\li FL_SYMBOL - Standard symbol font. -\li FL_SCREEN - Default monospaced screen font. -\li FL_SCREEN_BOLD - Default monospaced bold screen font. -\li FL_ZAPF_DINGBATS - Zapf-dingbats font. - - -\section enumerations_colors Colors - -The Fl_Color enumeration type holds a FLTK color value. -Colors are either 8-bit indexes into a virtual colormap or 24-bit RGB -color values. Color indices occupy the lower 8 bits of the value, while -RGB colors occupy the upper 24 bits, for a byte organization of RGBI. - -\subsection enumerations_color_constants Color Constants - -Constants are defined for the user-defined foreground and background -colors, as well as specific colors and the start of the grayscale ramp -and color cube in the virtual colormap. Inline functions are provided to -retrieve specific grayscale, color cube, or RGB color values. - -The following color constants can be used to access the user-defined -colors: - -\li FL_BACKGROUND_COLOR - the default background color -\li FL_BACKGROUND2_COLOR - the default - background color for text, list, and valuator widgets -\li FL_FOREGROUND_COLOR - the default - foreground color (0) used for labels and text -\li FL_INACTIVE_COLOR - the inactive foreground color -\li FL_SELECTION_COLOR - the default selection/highlight color - -The following color constants can be used to access the colors from the -FLTK standard color cube: - -\li FL_BLACK -\li FL_BLUE -\li FL_CYAN -\li FL_DARK_BLUE -\li FL_DARK_CYAN -\li FL_DARK_GREEN -\li FL_DARK_MAGENTA -\li FL_DARK_RED -\li FL_DARK_YELLOW -\li FL_GREEN -\li FL_MAGENTA -\li FL_RED -\li FL_WHITE -\li FL_YELLOW - -The following are named values within the standard grayscale: - -\li FL_GRAY0 -\li FL_DARK3 -\li FL_DARK2 -\li FL_DARK1 -\li FL_LIGHT1 -\li FL_LIGHT2 -\li FL_LIGHT3 - -The inline methods for getting a grayscale, color cube, or -RGB color value are described in the -\ref drawing_colors -section of the -\ref drawing -chapter. - - -\section enumerations_cursors Cursors - -The following constants define the mouse cursors that are available in -FLTK. The double-headed arrows are bitmaps -provided by FLTK on X, the others are provided by system-defined -cursors. - - -\li FL_CURSOR_DEFAULT - the default cursor, usually an arrow (0) -\li FL_CURSOR_ARROW - an arrow pointer -\li FL_CURSOR_CROSS - crosshair -\li FL_CURSOR_WAIT - watch or hourglass -\li FL_CURSOR_INSERT - I-beam -\li FL_CURSOR_HAND - hand (uparrow on MSWindows) -\li FL_CURSOR_HELP - question mark -\li FL_CURSOR_MOVE - 4-pointed arrow -\li FL_CURSOR_NS - up/down arrow -\li FL_CURSOR_WE - left/right arrow -\li FL_CURSOR_NWSE - diagonal arrow -\li FL_CURSOR_NESW - diagonal arrow -\li FL_CURSOR_NONE - invisible - - -\section enumerations_file_when FD "When" Conditions - -\li FL_READ - Call the callback when there is data to be - read. -\li FL_WRITE - Call the callback when data can be written - without blocking. -\li FL_EXCEPT - Call the callback if an exception occurs on - the file. - - -\section enumerations_damage Damage Masks - -The following damage mask bits are used by the standard FLTK widgets: - -\li FL_DAMAGE_CHILD - A child needs to be redrawn. -\li FL_DAMAGE_EXPOSE - The window was exposed. -\li FL_DAMAGE_SCROLL - The Fl_Scroll widget was scrolled. -\li FL_DAMAGE_OVERLAY - The overlay planes need to be redrawn. -\li FL_DAMAGE_USER1 - First user-defined damage bit. -\li FL_DAMAGE_USER2 - Second user-defined damage bit. -\li FL_DAMAGE_ALL - Everything needs to be redrawn. - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="unicode.html"> - [Prev] - Unicode and UTF-8 Support - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="glut.html"> - GLUT Compatibility - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/events.dox b/branch-3.0-2011/documentation/src/events.dox deleted file mode 100644 index 73920feaf..000000000 --- a/branch-3.0-2011/documentation/src/events.dox +++ /dev/null @@ -1,458 +0,0 @@ -/** - - \page events Handling Events - -This chapter discusses the FLTK event model and how to handle -events in your program or widget. - -\section events_model The FLTK Event Model - -Every time a user moves the mouse pointer, clicks a button, -or presses a key, an event is generated and sent to your -application. Events can also come from other programs like the -window manager. - -Events are identified by the integer argument passed to a -\p handle() method that overrides the -Fl_Widget::handle() -virtual method. -Other information about the most recent event is stored in -static locations and acquired by calling the -\ref events_event_xxx. -This static information remains valid until the next event -is read from the window system, so it is ok to look at it outside -of the -\p handle() -method. - -Event numbers can be converted to their actual names using the \ref fl_eventnames[] array -defined in \#include <FL/names.h>; see next chapter for details. - -In the next chapter, the -\ref subclassing_events "MyClass::handle()" -example shows how to override the -Fl_Widget::handle() -method to accept and process specific events. - -\section events_mouse Mouse Events - -\subsection events_fl_push 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 \e "wants" the mouse click -by returning non-zero from its -\p handle() -method, as in the -\ref subclassing_events "MyClass::handle()" -example. -It will then become the -Fl::pushed() -widget and will get \p FL_DRAG and -the matching \p FL_RELEASE events. -If -\p handle() -returns zero then FLTK will try sending the \p FL_PUSH to -another widget. - -\subsection events_fl_drag FL_DRAG - -The mouse has moved with a button held down. The current -button state is in -Fl::event_state(). -The mouse position is in -Fl::event_x() -and -Fl::event_y(). - -In order to receive \p FL_DRAG events, the widget must -return non-zero when handling \p FL_PUSH. - -\subsection events_fl_release FL_RELEASE - -A mouse button has been released. You can find out what button by calling -Fl::event_button(). - -In order to receive the \p FL_RELEASE event, the widget must -return non-zero when handling \p FL_PUSH. - -\subsection events_fl_move FL_MOVE - -The mouse has moved without any mouse buttons held down. -This event is sent to the -Fl::belowmouse() -widget. - -In order to receive \p FL_MOVE events, the widget must -return non-zero when handling \p FL_ENTER. - -\subsection events_fl_mousewheel FL_MOUSEWHEEL - -The user has moved the mouse wheel. The -Fl::event_dx() -and -Fl::event_dy() -methods can be used to find the amount to scroll horizontally and -vertically. - -\section events_focus Focus Events - -\subsection events_fl_enter 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 -\p handle() -method. It then becomes the -Fl::belowmouse() -widget and will receive \p FL_MOVE and \p FL_LEAVE -events. - -\subsection events_fl_leave FL_LEAVE - -The mouse has moved out of the widget. - -In order to receive the \p FL_LEAVE event, the widget must -return non-zero when handling \p FL_ENTER. - -\subsection events_fl_focus FL_FOCUS - -This indicates an \e 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 -\p handle() -method. It then becomes the -Fl::focus() -widget and gets -\p FL_KEYDOWN, \p FL_KEYUP, and \p 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 interaction with the window manager it will be zero. - -\subsection events_fl_unfocus FL_UNFOCUS - -This event is sent to the previous -Fl::focus() -widget when another widget gets the focus or the window loses focus. - -\section events_keyboard Keyboard Events - -\subsection events_fl_keydown FL_KEYDOWN, FL_KEYUP - -A key was pressed or released. The key 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, then -\p handle() -should return 1. If you -return zero then FLTK assumes you ignored the key and will -then attempt to send it to a parent widget. If none of them want -it, it will change the event into a \p FL_SHORTCUT event. -FL_KEYBOARD events are also generated by the character palette/map. - -To receive \p FL_KEYBOARD events you must also -respond to the \p FL_FOCUS and \p FL_UNFOCUS -events. - -If you are writing a text-editing widget you may also want to call the -Fl::compose() -function to translate individual keystrokes into characters. - -\p FL_KEYUP events are sent to the widget that -currently has focus. This is not necessarily the same widget -that received the corresponding \p FL_KEYDOWN event -because focus may have changed between events. - -\subsection events_fl_shortcut FL_SHORTCUT - -If the -Fl::focus() -widget is zero or ignores an \p FL_KEYBOARD event then -FLTK tries sending this event to every widget it can, until one -of them returns non-zero. \p FL_SHORTCUT is first sent to -the Fl::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. - -\section events_widget Widget Events - -\subsection events_fl_deactivate FL_DEACTIVATE - -This widget is no longer active, due to -\ref Fl_Widget::deactivate() "deactivate()" -being called on it or one of its parents. -Please note that although -\ref Fl_Widget::active() "active()" -may still return true for this widget after receiving this event, -it is only truly active if -\ref Fl_Widget::active() "active()" -is true for both it and all of its parents. -(You can use -\ref Fl_Widget::active_r() "active_r()" -to check this). - -\subsection events_fl_activate FL_ACTIVATE - -This widget is now active, due to -\ref Fl_Widget::activate() "activate()" -being called on it or one of its parents. - -\subsection events_fl_hide FL_HIDE - -This widget is no longer visible, due to -\ref Fl_Widget::hide() "hide()" -being called on it or one of its parents, or due to a parent window -being minimized. -Please note that although -\ref Fl_Widget::visible() "visible()" -may still return true for this widget after receiving this event, -it is only truly visible if -\ref Fl_Widget::visible() "visible()" -is true for both it and all of its parents. -(You can use -\ref Fl_Widget::visible_r() "visible_r()" -to check this). - -\subsection events_fl_show FL_SHOW - -This widget is visible again, due to -\ref Fl_Widget::show() "show()" -being called on it or one of its parents, or due to a parent window -being restored. <I>A child Fl_Window will respond to this by -actually creating the window if not done already, so if you -subclass a window, be sure to pass \p FL_SHOW to the base -class -\p handle() -method!</I> - -\section events_clipboard Clipboard Events - -\subsection events_fl_paste 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(). - -\subsection events_fl_selectionclear 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. Motif programs used this to clear the -selection indication. Most modern programs ignore this. - -\section events_dnd Drag and Drop Events - -FLTK supports drag and drop of text and files from any -application on the desktop to an FLTK widget. Text is transfered using -the current code page. Files are received as a list of full path -and file names, separated by newline. On some platforms, path -names are prepended with <tt>%file://</tt>. -See Fl::dnd() for drag and drop from an FLTK widget. - -The drag and drop data is available in Fl::event_text() -at the concluding \p FL_PASTE. On some platforms, the -event text is also available for the \p FL_DND_* events, -however application must not depend on that behavior because it -depends on the protocol used on each platform. - -\p FL_DND_* events cannot be used in widgets derived -from Fl_Group or Fl_Window. - -\subsection events_fl_dnd_enter FL_DND_ENTER - -The mouse has been moved to point at this widget. A widget that is -interested in receiving drag'n'drop data must return 1 to receive -\p FL_DND_DRAG, \p FL_DND_LEAVE and \p FL_DND_RELEASE events. - -\subsection events_fl_dnd_drag FL_DND_DRAG - -The mouse has been moved inside a widget while dragging data. -A widget that is interested in receiving drag'n'drop data should -indicate the possible drop position. - -\subsection events_fl_dnd_leave FL_DND_LEAVE - -The mouse has moved out of the widget. - -\subsection events_fl_dnd_release FL_DND_RELEASE - -The user has released the mouse button dropping data into -the widget. If the widget returns 1, it will receive the data in -the immediately following \p FL_PASTE event. - -<!-- NEED 6in --> - -\section events_event_xxx 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 -\p handle() -and -\p callback() -methods. - -These are all trivial inline functions and thus very fast and small: - -\li Fl::event_button() -\li Fl::event_clicks() -\li Fl::event_dx() -\li Fl::event_dy() -\li Fl::event_inside() -\li Fl::event_is_click() -\li Fl::event_key() -\li Fl::event_length() -\li Fl::event_state() -\li Fl::event_text() -\li Fl::event_x() -\li Fl::event_x_root() -\li Fl::event_y() -\li Fl::event_y_root() -\li Fl::get_key() -\li Fl::get_mouse() -\li Fl::test_shortcut() - -\section events_propagation Event Propagation - -Widgets receive events via the virtual handle() function. The argument indicates -the type of event that can be handled. The widget must indicate if it handled the -event by returning 1. FLTK will then remove the event and wait for further events -from the host. If the widget's handle function returns 0, FLTK may redistribute -the event based on a few rules. - -Most events are sent directly to the -\p 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 -(\p FL_DRAG, \p FL_RELEASE, \p FL_KEYBOARD, -\p FL_SHORTCUT, \p FL_UNFOCUS, and -\p FL_LEAVE) directly to leaf widgets. These procedures -control those leaf widgets: - -\li Fl::add_handler() -\li Fl::belowmouse() -\li Fl::focus() -\li Fl::grab() -\li Fl::modal() -\li Fl::pushed() -\li Fl::release() -\li Fl_Widget::take_focus() - -FLTK propagates events along the widget hierarchy depending on the kind of event -and the status of the UI. Some events are injected directly into the widgets, -others may be resent as new events to a different group of receivers. - -Mouse click events are first sent to the window that caused them. The window -then forwards the event down the hierarchy until it reaches the widget that -is below the click position. If that widget uses the given event, the widget -is marked "pushed" and will receive all following mouse motion (FL_DRAG) events -until the mouse button is released. - -\todo Is this correct? IMHO, mouse motion (FL_MOVE) events are sent to the -belowmouse() widget, i.e. the widget that returned 1 on an FL_ENTER event. -The pushed() widget will usually get an FL_FOCUS event and becomes the focus() -widget if it returns 1 on FL_FOCUS, and will then get keyboard events (see -below). - -Mouse wheel events are sent to the window that caused the event. The window -propagates the event down the tree, first to the widget that is below the -mouse pointer, and if that does not succeed, to all other widgets in the group. -This ensures that scroll widgets work as expected with the widget furthest -down in the hierarchy getting the first opportunity to use the wheel event, -but also giving scroll bars, that are not directly below the mouse a chance. - -Keyboard events are sent directly to the widget that has keyboard focus. -If the focused widget rejects the event, it is resent as a shortcut event, -first to the top-most window, then to the widget below the mouse pointer, -propagating up the hierarchy to all its parents. Those send the event also -to all widgets that are not below the mouse pointer. Now if that did not work -out, the shortcut is sent to all registered shortcut handlers. - -If we are still unsuccessful, the event handler flips the case of the shortcut -letter and starts over. Finally, if the key is "escape", FLTK sends a close -event to the top-most window. - -All other events are pretty much sent right away to the window that created -the event. - -Widgets can "grab" events. The grabbing window gets all events exclusively, but -usually by the same rules as described above. - -Windows can also request exclusivity in event handling by making the -window modal. - - -\section events_compose_characters FLTK Compose-Character Sequences - -The character composition done by Fl_Input widget -requires that you call the Fl::compose() function if you are -writing your own text editor widget. - -Currently, all characters made by single key strokes -with or without modifier keys, or by system-defined character -compose sequences (that can involve dead keys or a compose key) can be input. -You should call Fl::compose() in case any -enhancements to this processing are done in the future. The -interface has been designed to handle arbitrary UTF-8 encoded -text. - -The following methods are provided for character composition: - -\li Fl::compose() -\li Fl::compose_reset() - -Under Mac OS X, FLTK "previews" partially composed sequences. - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="drawing.html"> - [Prev] - Drawing Things in FLTK - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="subclassing.html"> - Adding and Extending Widgets - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/examples.dox b/branch-3.0-2011/documentation/src/examples.dox deleted file mode 100644 index 556312b9d..000000000 --- a/branch-3.0-2011/documentation/src/examples.dox +++ /dev/null @@ -1,610 +0,0 @@ -/** - - \page examples Example Source Code - -The FLTK distribution contains over 60 sample applications written -in, or ported to, FLTK. If the FLTK archive you received does not -contain a 'test' directory, you can download the complete FLTK -distribution from \b http://fltk.org/software.php . - -Most of the example programs were created while testing a group of widgets. -They are not meant to be great achievements in clean C++ programming, but -merely a test platform to verify the functionality of the FLTK library. - -Note that extra example programs are also available in an additional -'examples' directory, but these are \b NOT built automatically when -you build FLTK, unlike those in the 'test' directory shown below. - -\section example_applications Example Applications - -<table width=100% border=0> -<tr> -<td> \ref examples_adjuster </td> -<td> \ref examples_arc </td> -<td> \ref examples_ask </td> -<td> \ref examples_bitmap </td> -<td> \ref examples_blocks </td> -<td> \ref examples_boxtype </td> -</tr> -<tr> -<td> \ref examples_browser </td> -<td> \ref examples_button </td> -<td> \ref examples_buttons </td> -<td> \ref examples_checkers </td> -<td> \ref examples_clock </td> -<td> \ref examples_colbrowser </td> -</tr> -<tr> -<td> \ref examples_color_chooser </td> -<td> \ref examples_cube </td> -<td> \ref examples_CubeView </td> -<td> \ref examples_cursor </td> -<td> \ref examples_curve </td> -<td> \ref examples_demo </td> -</tr> -<tr> -<td> \ref examples_doublebuffer </td> -<td> \ref examples_editor </td> -<td> \ref examples_fast_slow </td> -<td> \ref examples_file_chooser </td> -<td> \ref examples_fluid </td> -<td> \ref examples_fonts </td> -</tr> -<tr> -<td> \ref examples_forms </td> -<td> \ref examples_fractals </td> -<td> \ref examples_fullscreen </td> -<td> \ref examples_gl_overlay </td> -<td> \ref examples_glpuzzle </td> -<td> \ref examples_hello </td> -</tr> -<tr> -<td> \ref examples_help </td> -<td> \ref examples_iconize </td> -<td> \ref examples_image </td> -<td> \ref examples_inactive </td> -<td> \ref examples_input </td> -<td> \ref examples_input_choice </td> -</tr> -<tr> -<td> \ref examples_keyboard </td> -<td> \ref examples_label </td> -<td> \ref examples_line_style </td> -<td> \ref examples_list_visuals </td> -<td> \ref examples_mandelbrot </td> -<td> \ref examples_menubar </td> -</tr> -<tr> -<td> \ref examples_message </td> -<td> \ref examples_minimum </td> -<td> \ref examples_navigation </td> -<td> \ref examples_output </td> -<td> \ref examples_overlay </td> -<td> \ref examples_pack </td> -</tr> -<tr> -<td> \ref examples_pixmap_browser </td> -<td> \ref examples_pixmap </td> -<td> \ref examples_preferences </td> -<td> \ref examples_radio </td> -<td> \ref examples_resizebox </td> -<td> \ref examples_resize </td> -</tr> -<tr> -<td> \ref examples_scroll </td> -<td> \ref examples_shape </td> -<td> \ref examples_subwindow </td> -<td> \ref examples_sudoku </td> -<td> \ref examples_symbols </td> -<td> \ref examples_tabs </td> -</tr> -<tr> -<td> \ref examples_threads </td> -<td> \ref examples_tile </td> -<td> \ref examples_tiled_image </td> -<td> \ref examples_valuators </td> -<td> \ref examples_device </td> -<td> </td> -<td> </td> -</tr> -</table> - -\subsection examples_adjuster adjuster - -\par -\c adjuster shows a nifty little widget for quickly -setting values in a great range. - -\subsection examples_arc arc - -\par -The \c arc demo explains how to derive your own widget to -generate some custom drawings. The sample drawings use the matrix -based arc drawing for some fun effects. - -\subsection examples_ask ask - -\par -\c ask shows some of FLTK's standard dialog boxes. Click -the correct answers or you may end up in a loop, or you may end -up in a loop, or you... . - -\subsection examples_bitmap bitmap - -\par -This simple test shows the use of a single color bitmap as a -label for a box widget. Bitmaps are stored in the X11 '.bmp' -file format and can be part of the source code. - -\subsection examples_blocks blocks - -\par -A wonderful and addictive game that shows the usage of FLTK -timers, graphics, and how to implement sound on all platforms. -\c blocks is also a good example for the Mac OS X specific -bundle format. - -\subsection examples_boxtype boxtype - -\par -\c boxtype gives an overview of readily available boxes and -frames in FLTK. More types can be added by the application programmer. -When using themes, FLTK shuffles boxtypes around to give your program -a new look. - -\subsection examples_browser browser - -\par -\c browser shows the capabilities of the Fl_Browser widget. -Important features tested are loading of files, line formatting, and -correct positioning of the browser data window. - -\subsection examples_button button - -\par -The \c button test is a simple demo of push-buttons and callbacks. - -\subsection examples_buttons buttons - -\par -\c buttons shows a sample of FLTK button types. - -\subsection examples_checkers checkers - -\par -Written by Steve Poulsen in early 1979, \c checkers shows -how to convert a VT100 text-terminal based program into a neat -application with a graphical UI. Check out the code that drags the -pieces, and how the pieces are drawn by layering. Then tell me -how to beat the computer at Checkers. - -\subsection examples_clock clock - -\par -The \c clock demo shows two analog clocks. The innards of -the Fl_Clock widget are pretty interesting, explaining -the use of timeouts and matrix based drawing. - -\subsection examples_colbrowser colbrowser - -\par -\c colbrowser runs only on X11 systems. It reads -<i>/usr/lib/X11/rgb.txt</i> to show the color representation -of every text entry in the file. This is beautiful, but -only moderately useful unless your UI is written in <i>Motif</i>. - -\subsection examples_color_chooser color_chooser - -\par -The \c color_chooser gives a short demo of FLTK's palette based -color chooser and of the RGB based color wheel. - -\subsection examples_cube cube - -\par -The \c cube demo shows the speed of OpenGL. It also tests -the ability to render two OpenGL buffers into a single window, -and shows OpenGL text. - -\subsection examples_CubeView CubeView - -\par -\c CubeView shows how to create a UI containing OpenGL with Fluid. - -\subsection examples_cursor cursor - -\par -The \c cursor demo shows all mouse cursor shapes that come standard -with FLTK. The <i>fgcolor</i> and <i>bgcolor</i> sliders work only -on few systems (some version of Irix for example). - -\subsection examples_curve curve - -\par -\c curve draws a nice Bezier curve into a custom widget. The -<i>points</i> option for splines is not supported on all platforms. - -\subsection examples_demo demo - -\par -This tool allows quick access to all programs in the \c test directory. -\c demo is based on the visuals of the IrixGL demo program. The menu -tree can be changed by editing <tt>test/demo.menu</tt>. - -\subsection examples_device device - -\par -Shows how a wide variety of graphics requests can be printed using the Fl_Printer class. - -\subsection examples_doublebuffer doublebuffer - -\par -The \c doublebuffer demo shows the difference between a single -buffered window, which may flicker during a slow redraw, and a -double buffered window, which never flickers, but uses twice the -amount of RAM. Some modern OS's double buffer all windows automatically -to allow transparency and shadows on the desktop. FLTK is smart enough -to not tripple buffer a window in that case. - -\subsection examples_editor editor - -\par -FLTK has two very different text input widgets. Fl_Input -and derived classes are rather light weight, however -Fl_Text_Editor is a complete port of <i>nedit</i> (with permission). -The \c editor test is almost a full application, showing custom -syntax highlighting and dialog creation. - -\subsection examples_fast_slow fast_slow - -\par -\c fast_slow shows how an application can use the Fl_Widget::when() -setting to receive different kinds of callbacks. - -\subsection examples_file_chooser file_chooser - -\par -The standard FLTK \c file_chooser is the result of many -iterations, trying to find a middle ground between a complex -browser and a fast light implementation. - -\subsection examples_fonts fonts - -\par -\c fonts shows all available text fonts on the host system. -If your machine still has some pixmap based fonts, the supported -sizes will be shown in bold face. Only the first 256 fonts will -be listed. - -\subsection examples_forms forms - -\par -\c forms is an XForms program with very few changes. -Search for "fltk" to find all changes necessary to port to fltk. -This demo shows the different boxtypes. Note that some -boxtypes are not appropriate for some objects. - -\subsection examples_fractals fractals - -\par -\c fractals shows how to mix OpenGL, Glut and FLTK code. -FLTK supports a rather large subset of Glut, so that many Glut -applications compile just fine. - -\subsection examples_fullscreen fullscreen - -\par -This demo shows how to do many of the window manipulations that -are popular for games. -You can toggle the border on/off, switch between single- -and double-buffered rendering, and take over the entire -screen. More information in the source code. - -\subsection examples_gl_overlay gl_overlay - -\par -\c gl_overlay shows OpenGL overlay plane rendering. If no -hardware overlay plane is available, FLTK will simulate it -for you. - -\subsection examples_glpuzzle glpuzzle - -\par -The \c glpuzzle test shows how most Glut source code compiles -easily under FLTK. - -\subsection examples_hello hello - -\par -\c hello: Hello, World. Need I say more? Well, maybe. This -tiny demo shows how little is needed to get a functioning application -running with FLTK. Quite impressive, I'd say. - -\subsection examples_help help - -\par -\c help displays the built-in FLTK help browser. The -Fl_Help_Dialog understands a subset of html and renders -various image formats. This widget makes it easy to provide help -pages to the user without depending on the operating system's -html browser. - -\subsection examples_iconize iconize - -\par -\c iconize demonstrates the effect of the window functions -hide(), iconize(), and show(). - -\subsection examples_image image - -\par -The \c image demo shows how an image can be created on the fly. -This generated image contains an alpha (transparency) channel which -lets previous renderings 'shine through', either via true -transparency or by using screen door transparency (pixelation). - -\subsection examples_inactive inactive - -\par -\c inactive tests the correct rendering of inactive widgets. -To see the inactive version of images, you can check out the pixmap -or image test. - -\subsection examples_input input - -\par -This tool shows and tests different types of text input fields based on -Fl_Input_. The \c input program also tests various -settings of Fl_Input::when(). - -\subsection examples_input_choice input_choice - -\par -\c input_choice tests the latest addition to FLTK1, a text input -field with an attached pulldown menu. Windows users will recognize -similarities to the 'ComboBox'. \c input_choice starts up in -'plastic' scheme, but the traditional scheme is also supported. - -\subsection examples_keyboard keyboard - -\par -FLTK unifies keyboard events for all platforms. The \c keyboard -test can be used to check the return values of Fl::event_key() -and Fl::event_text(). It is also great to see the modifier -buttons and the scroll wheel at work. Quit this application by closing -the window. The ESC key will not work. - -\subsection examples_label label - -\par -Every FLTK widget can have a label attached to it. The \c label -demo shows alignment, clipping, and wrapping of text labels. Labels -can contain symbols at the start and end of the text, like <i>\@FLTK</i> -or <i>\@circle uh-huh \@square</i>. - -\subsection examples_line_style line_style - -\par -Advanced line drawing can be tested with \c line_style. -Not all platforms support all line styles. - -\subsection examples_list_visuals list_visuals - -\par -This little app finds all available pixel formats for the current X11 -screen. But since you are now an FLTK user, you don't have to worry -about any of this. - -\subsection examples_mandelbrot mandelbrot - -\par -\c mandelbrot shows two advanced topics in one test. It creates -grayscale images on the fly, updating them via the <i>idle</i> callback -system. This is one of the few occasions where the <i>idle</i> callback -is very useful by giving all available processor time to the application -without blocking the UI or other apps. - -\subsection examples_menubar menubar - -\par -The \c menubar tests many aspects of FLTK's popup menu system. -Among the features are radio buttons, menus taller than the screen, -arbitrary sub menu depth, and global shortcuts. - -\subsection examples_message message - -\par -\c message pops up a few of FLTK's standard message boxes. - -\subsection examples_minimum minimum - -\par -The \c minimum test program verifies that the update regions -are set correctly. In a real life application, the trail would -be avoided by choosing a smaller label or by setting label clipping -differently. - -\subsection examples_navigation navigation - -\par -\c navigation demonstrates how the text cursor moves from -text field to text field when using the arrow keys, tab, and shift-tab. - -\subsection examples_output output - -\par -\c output shows the difference between the single line and -multi line mode of the Fl_Output widget. Fonts can be -selected from the FLTK standard list of fonts. - -\subsection examples_overlay overlay - -\par -The \c overlay test app shows how easy an FLTK window can -be layered to display cursor and manipulator style elements. This -example derives a new class from Fl_Overlay_Window and -provides a new function to draw custom overlays. - -\subsection examples_pack pack - -\par -The \c pack test program demonstrates the resizing -and repositioning of children of the Fl_Pack group. -Putting an Fl_Pack into an Fl_Scroll is -a useful way to create a browser for large sets of data. - -\subsection examples_pixmap_browser pixmap_browser - -\par -\c pixmap_browser tests the shared-image interface. When using -the same image multiple times, Fl_Shared_Image will keep it -only once in memory. - -\subsection examples_pixmap pixmap - -\par -This simple test shows the use of a LUT based pixmap as a -label for a box widget. Pixmaps are stored in the X11 '.xpm' -file format and can be part of the source code. Pixmaps support -one transparent color. - -\subsection examples_preferences preferences - -\par -I do have my \c preferences in the morning, but sometimes I -just can't remember a thing. This is where the Fl_Preferences -come in handy. They remember any kind of data between program launches. - -\subsection examples_radio radio - -\par -The \c radio tool was created entirely with <i>fluid</i>. It -shows some of the available button types and tests radio -button behavior. - -\subsection examples_resizebox resizebox - -\par -\c resizebox shows some possible ways of FLTK's automatic -resize behavior. - -\subsection examples_resize resize - -\par -The \c resize demo tests size and position functions with -the given window manager. - -\subsection examples_scroll scroll - -\par -\c scroll shows how to scroll an area of widgets, one of -them being a slow custom drawing. Fl_Scroll uses -clipping and smart window area copying to improve redraw speed. -The buttons at the bottom of the window control decoration rendering -and updates. - -\subsection examples_shape shape - -\par -\c shape is a very minimal demo that shows how to create -your own OpenGL rendering widget. Now that you know that, go ahead -and write that flight simulator you always dreamt of. - -\subsection examples_subwindow subwindow - -\par -The \c subwindow demo tests messaging and drawing between -the main window and 'true' sub windows. A sub window is different -to a group by resetting the FLTK coordinate system to 0, 0 in the -top left corner. On Win32 and X11, subwindows have their own -operating system specific handle. - -\subsection examples_sudoku sudoku - -\par -Another highly addictive game - don't play it, I warned you. -The implementation shows how to create application icons, -how to deal with OS specifics, and how to generate sound. - -\subsection examples_symbols symbols - -\par -\c symbols are a speciality of FLTK. These little vector -drawings can be integrated into labels. They scale and rotate, -and with a little patience, you can define your own. The rotation -number refers to 45 degree rotations if you were looking at a -numeric keypad (2 is down, 6 is right, etc.). - -\subsection examples_tabs tabs - -\par -The \c tabs tool was created with <i>fluid</i>. It tests -correct hiding and redisplaying of tabs, navigation across tabs, -resize behavior, and no unneeded redrawing of invisible widgets. - -\par -The \c tabs application shows the Fl_Tabs widget -on the left and the Fl_Wizard widget on the right side -for direct comparison of these two panel management widgets. - -\subsection examples_threads threads - -\par -FLTK can be used in a multithreading environment. There are some -limitations, mostly due to the underlying operating system. -\c threads shows how to use Fl::lock(), -Fl::unlock(), and Fl::awake() in secondary threads -to keep FLTK happy. Although locking works on all platforms, -this demo is not available on every machine. - -\subsection examples_tile tile - -\par -The \c tile tool shows a nice way of using Fl_Tile. -To test correct resizing of subwindows, the widget for region -1 is created from an Fl_Window class. - -\subsection examples_tiled_image tiled_image - -\par -The \c tiled_image demo uses an image as the background -for a window by repeating it over the full size of the widget. -The window is resizable and shows how the image gets repeated. - -\subsection examples_valuators valuators - -\par -\c valuators shows all of FLTK's nifty widgets to change -numeric values. - -\subsection examples_fluid fluid - -\par -\c fluid is not only a big test program, but also a very -useful visual UI designer. Many parts of \c fluid were -created using \c fluid. See the \link fluid Fluid Tutorial \endlink -for more details. - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="license.html"> - [Prev] - Software License - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/fl_alert.png b/branch-3.0-2011/documentation/src/fl_alert.png Binary files differdeleted file mode 100644 index 0c06fa46f..000000000 --- a/branch-3.0-2011/documentation/src/fl_alert.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fl_ask.png b/branch-3.0-2011/documentation/src/fl_ask.png Binary files differdeleted file mode 100644 index 39b9c3da4..000000000 --- a/branch-3.0-2011/documentation/src/fl_ask.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fl_choice.png b/branch-3.0-2011/documentation/src/fl_choice.png Binary files differdeleted file mode 100644 index 7e33f35ea..000000000 --- a/branch-3.0-2011/documentation/src/fl_choice.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fl_color_chooser.jpg b/branch-3.0-2011/documentation/src/fl_color_chooser.jpg Binary files differdeleted file mode 100644 index 55dd82f07..000000000 --- a/branch-3.0-2011/documentation/src/fl_color_chooser.jpg +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fl_input.png b/branch-3.0-2011/documentation/src/fl_input.png Binary files differdeleted file mode 100644 index efffd09a6..000000000 --- a/branch-3.0-2011/documentation/src/fl_input.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fl_message.png b/branch-3.0-2011/documentation/src/fl_message.png Binary files differdeleted file mode 100644 index 0464000f6..000000000 --- a/branch-3.0-2011/documentation/src/fl_message.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fl_password.png b/branch-3.0-2011/documentation/src/fl_password.png Binary files differdeleted file mode 100644 index d268c2ba8..000000000 --- a/branch-3.0-2011/documentation/src/fl_password.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fl_show_colormap.png b/branch-3.0-2011/documentation/src/fl_show_colormap.png Binary files differdeleted file mode 100644 index efb2f7c64..000000000 --- a/branch-3.0-2011/documentation/src/fl_show_colormap.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fltk-book.tex b/branch-3.0-2011/documentation/src/fltk-book.tex deleted file mode 100644 index f31fd2c8c..000000000 --- a/branch-3.0-2011/documentation/src/fltk-book.tex +++ /dev/null @@ -1,58 +0,0 @@ -\documentclass[a4paper]{book} -\usepackage{a4wide} -\usepackage{makeidx} -\usepackage{fancyhdr} -\usepackage{graphicx} -\usepackage{multicol} -\usepackage{float} -\usepackage{textcomp} -\usepackage{alltt} -\usepackage{times} -\usepackage{ifpdf} -\ifpdf -\usepackage[pdftex, - pagebackref=true, - colorlinks=true, - linkcolor=blue, - unicode - ]{hyperref} -\else -\usepackage[ps2pdf, - pagebackref=true, - colorlinks=true, - linkcolor=blue, - unicode - ]{hyperref} -\usepackage{pspicture} -\fi -\usepackage[utf8]{inputenc} -\usepackage{doxygen} -\makeindex -\setcounter{tocdepth}{1} -\renewcommand{\footrulewidth}{0.4pt} -\begin{document} -\begin{titlepage} -\vspace*{4.5cm} -\begin{center} -{\Huge FLTK 1.3.0 Programming Manual}\\ -\vspace*{2cm} -\begin{ImageNoCaption} - \mbox{\includegraphics[width=6cm]{FL200}} -\end{ImageNoCaption}\\ -\vspace*{2cm} -{\Large -Revision 9 by F. Costantini, D. Gibson, M. Melcher, \\ -A. Schlosser, B. Spitzak and M. Sweet.}\\ -\vspace*{1.5cm} -{\large Copyright 1998-2010 by Bill Spitzak and others.}\\ -\vspace*{3.5cm} -{\large Generated by Doxygen 1.5.7.1}\\ -\vspace*{0.5cm} -\today{}\\ -\end{center} -\end{titlepage} -\clearemptydoublepage -\pagenumbering{roman} -\tableofcontents -\clearemptydoublepage -\pagenumbering{arabic} diff --git a/branch-3.0-2011/documentation/src/fltk-config.man b/branch-3.0-2011/documentation/src/fltk-config.man deleted file mode 100644 index 2fc3b7f09..000000000 --- a/branch-3.0-2011/documentation/src/fltk-config.man +++ /dev/null @@ -1,90 +0,0 @@ -.TH fltk\-config 1 "Fast Light Tool Kit" "6 February 2007" -.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 ] -[ \-\-cc ] [ \-\-cxx ] -[ \-\-cflags ] [ \-\-cxxflags ] [ \-\-ldflags ] [ \-\-ldstaticflags ] -[ \-\-libs ] -[ \-D\fIname[=value]\fR ] [ \-g ] [ \-\-compile -.I program.cxx -] -.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 -\-\-cc -.TP 5 -\-\-cxx -.br -Displays the C/C++ compiler that was used to compile FLTK. -.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 -\-g -.br -Enables debugging information when compiling with the \fI\-\-compile\fR -option. -.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 -\-\-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/branch-3.0-2011/documentation/src/fltk.book b/branch-3.0-2011/documentation/src/fltk.book deleted file mode 100644 index acd4fcc0c..000000000 --- a/branch-3.0-2011/documentation/src/fltk.book +++ /dev/null @@ -1,108 +0,0 @@ -#HTMLDOC 1.8.27.1 --t pdf13 -f "fltk.pdf" --book --toclevels 2 --no-numbered --toctitle "Table of Contents" --title --titleimage "FL.gif" --linkstyle underline --size Universal --left 1.00in --right 0.50in --top 0.50in --bottom 0.50in --header .t. --header1 ... --footer h.1 --nup 1 --tocheader .t. --tocfooter ..i --duplex --portrait --color --no-pscommands --no-xrxcomments --compression=9 --jpeg=50 --fontsize 11.0 --fontspacing 1.2 --headingfont Helvetica --bodyfont Times --headfootsize 11.0 --headfootfont Helvetica --charset iso-8859-1 --links --no-embedfonts --pagemode outline --pagelayout single --firstpage c1 --pageeffect none --pageduration 10 --effectduration 1.0 --no-encryption --permissions all --owner-password "" --user-password "" --browserwidth 680 --strict --no-overflow -preface.html -intro.html -basics.html -common.html -editor.html -drawing.html -events.html -subclassing.html -opengl.html -fluid.html -widgets.html -advanced.html -Fl.html -Fl_Adjuster.html -Fl_Bitmap.html -Fl_BMP_Image.html -Fl_Box.html -Fl_Browser_.html -Fl_Browser.html -Fl_Button.html -Fl_Chart.html -Fl_Check_Browser.html -Fl_Check_Button.html -Fl_Choice.html -Fl_Clock.html -Fl_Clock_Output.html -Fl_Color_Chooser.html -Fl_Counter.html -Fl_Dial.html -Fl_Double_Window.html -Fl_End.html -Fl_File_Browser.html -Fl_File_Chooser.html -Fl_File_Icon.html -Fl_File_Input.html -Fl_Float_Input.html -Fl_Free.html -Fl_GIF_Image.html -Fl_Gl_Window.html -Fl_Group.html -Fl_Help_Dialog.html -Fl_Help_View.html -Fl_Hold_Browser.html -Fl_Image.html -Fl_Input.html -Fl_Input_.html -Fl_Input_Choice.html -Fl_Int_Input.html -Fl_JPEG_Image.html -Fl_Light_Button.html -Fl_Menu_.html -Fl_Menu_Bar.html -Fl_Menu_Button.html -Fl_Menu_Item.html -Fl_Menu_Window.html -Fl_Multi_Browser.html -Fl_Multiline_Input.html -Fl_Multiline_Output.html -Fl_Output.html -Fl_Overlay_Window.html -Fl_Pack.html -Fl_Pixmap.html -Fl_PNG_Image.html -Fl_PNM_Image.html -Fl_Positioner.html -Fl_Preferences.html -Fl_Progress.html -Fl_Repeat_Button.html -Fl_RGB_Image.html -Fl_Return_Button.html -Fl_Roller.html -Fl_Round_Button.html -Fl_Scroll.html -Fl_Scrollbar.html -Fl_Secret_Input.html -Fl_Select_Browser.html -Fl_Shared_Image.html -Fl_Single_Window.html -Fl_Slider.html -Fl_Spinner.html -Fl_Tabs.html -Fl_Text_Buffer.html -Fl_Text_Display.html -Fl_Text_Editor.html -Fl_Tile.html -Fl_Tiled_Image.html -Fl_Timer.html -Fl_Toggle_Button.html -Fl_Tooltip.html -Fl_Valuator.html -Fl_Value_Input.html -Fl_Value_Output.html -Fl_Value_Slider.html -Fl_Widget.html -Fl_Window.html -Fl_Wizard.html -Fl_XBM_Image.html -Fl_XPM_Image.html -functions.html -enumerations.html -glut.html -forms.html -osissues.html -migration.html -license.html -examples.html diff --git a/branch-3.0-2011/documentation/src/fltk.man b/branch-3.0-2011/documentation/src/fltk.man deleted file mode 100644 index 8950712cd..000000000 --- a/branch-3.0-2011/documentation/src/fltk.man +++ /dev/null @@ -1,57 +0,0 @@ -.TH fltk 3 "Fast Light Tool Kit" "6 January 2002" -.SH NAME -fltk \- the fast light tool kit -.sp -.SH SYNOPSIS -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 -through the "Software Trouble Report" on the following page: -.IP - http://www.fltk.org/str.php -.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 -fltk\-config(1), fluid(1) -.br -FLTK Programming Manual -.br -FLTK Web Site, http://www.fltk.org/ -.SH AUTHORS -Bill Spitzak and others. diff --git a/branch-3.0-2011/documentation/src/fluid-catgets.png b/branch-3.0-2011/documentation/src/fluid-catgets.png Binary files differdeleted file mode 100644 index 363f74a1a..000000000 --- a/branch-3.0-2011/documentation/src/fluid-catgets.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fluid-gettext.png b/branch-3.0-2011/documentation/src/fluid-gettext.png Binary files differdeleted file mode 100644 index 83030626b..000000000 --- a/branch-3.0-2011/documentation/src/fluid-gettext.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fluid-org.png b/branch-3.0-2011/documentation/src/fluid-org.png Binary files differdeleted file mode 100644 index c3b60b797..000000000 --- a/branch-3.0-2011/documentation/src/fluid-org.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fluid.dox b/branch-3.0-2011/documentation/src/fluid.dox deleted file mode 100644 index d5ad3edca..000000000 --- a/branch-3.0-2011/documentation/src/fluid.dox +++ /dev/null @@ -1,1506 +0,0 @@ -/** - <!-- Warning: \p .fl does not work but <tt>.fl</tt> does --> - <!-- Warning: \p .h does not work but <tt>.h</tt> does --> - <!-- Warning: \p .cxx does not work but <tt>.cxx</tt> does --> - - \page fluid Programming with FLUID - -This chapter shows how to use the Fast Light User-Interface Designer -("FLUID") to create your GUIs. - -Subchapters: - -\li \ref fluid_what_is_fluid -\li \ref fluid_fluid_under_unix -\li \ref fluid_fluid_under_windows -\li \ref fluid_compiling_fl_files -\li \ref fluid_tutorial -\li \ref fluid_references -\li \ref fluid_i18n -\li \ref fluid_limitations - -\section fluid_what_is_fluid 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 <tt>.fl</tt> 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 <tt>.fl</tt> file into a -<tt>.cxx</tt> and a <tt>.h</tt> file. The <tt>.cxx</tt> file -defines all the objects from the <tt>.fl</tt> file and the -<tt>.h</tt> file declares all the global ones. FLUID also -supports localization (\ref fluid_i18n "Internationalization") -of label strings using message files and the GNU gettext or -POSIX catgets interfaces. - -A simple program can be made by putting all your code (including a -\p main() function) into the <tt>.fl</tt> file and thus making the -<tt>.cxx</tt> file a -single source file to compile. Most programs are more complex than -this, so you write other <tt>.cxx</tt> files that call the FLUID functions. -These <tt>.cxx</tt> files must -\p \#include -the <tt>.h</tt> file or they can -\p \#include -the <tt>.cxx</tt> file so it still appears to be a single source file. - - \image html fluid-org.png "Figure 9-1: FLUID organization" - \image latex fluid-org.png "FLUID organization" width=12cm - -Normally the FLUID file defines one or more functions or classes which -output C++ code. 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 <tt>'.'</tt> or <tt>'->'</tt> 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 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 <tt>.cxx</tt> file. - -\section fluid_fluid_under_unix Running FLUID Under UNIX - -To run FLUID under UNIX, type: - -\code -fluid filename.fl & -\endcode - -to edit the <tt>.fl</tt> file <tt>filename.fl</tt>. -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 filename: - -\code --display host:n.n --geometry WxH+X+Y --title windowtitle --name classname --iconic --fg color --bg color --bg2 color --scheme schemename -\endcode - -Changing the colors may be useful to see what your interface -will look at if the user calls it with the same switches. -Similarly, using "-scheme plastic" will show how the interface -will look using the "plastic" scheme. - -In the current version, if you don't put FLUID into the -background with <tt>'&'</tt> then you will be able to abort FLUID by -typing <tt>CTRL-C</tt> on the terminal. It will exit -immediately, losing any changes. - -\section fluid_fluid_under_windows Running FLUID Under Microsoft Windows - -To run FLUID under WIN32, double-click on the \e FLUID.exe -file. You can also run FLUID from the Command Prompt window. -FLUID always runs in the background under WIN32. - -\section fluid_compiling_fl_files Compiling .fl files - -FLUID can also be called as a command-line -"compiler" to create the <tt>.cxx</tt> and <tt>.h</tt> -file from a <tt>.fl</tt> file. To do this type: - -\code -fluid -c filename.fl -\endcode - -This will read the <tt>filename.fl</tt> file and write -<tt>filename.cxx</tt> and <tt>filename.h</tt>. Any leading -directory on <tt>filename.fl</tt> will be stripped, so they are -always written to the current directory. If there are any errors -reading or writing the files, FLUID will print the error and -exit with a non-zero code. You can use the following lines in a -makefile to automate the creation of the source and header -files: - -\code -my_panels.h my_panels.cxx: my_panels.fl - fluid -c my_panels.fl -\endcode - -Most versions of make support rules that cause <tt>.fl</tt> -files to be compiled: - -\code -.SUFFIXES: .fl .cxx .h -.fl.h .fl.cxx: - fluid -c $< -\endcode - -\section fluid_tutorial A Short Tutorial - -FLUID is an amazingly powerful little program. However, this -power comes at a price as it is not always obvious how to -accomplish seemingly simple tasks with it. This tutorial will -show you how to generate a complete user interface class with -FLUID that is used for the CubeView program provided with FLTK. - -\image html cubeview.png "Figure 9-2: CubeView demo" -\image latex cubeview.png "CubeView demo" width=10cm - -The window is of class CubeViewUI, and is completely generated by FLUID, -including -class member functions. The central display of the cube is a separate -subclass of Fl_Gl_Window called CubeView. CubeViewUI manages CubeView -using callbacks from the various sliders and rollers to manipulate the -viewing angle and zoom of CubeView. - -At the completion of this tutorial you will (hopefully) understand -how to: - --# Use FLUID to create a complete user interface class, including - constructor and any member functions necessary. --# Use FLUID to set callbacks member functions of a custom widget - classes. --# Subclass an Fl_Gl_Window to suit your purposes. - -\subsection fluid_cubeview The CubeView Class - -The CubeView class is a subclass of Fl_Gl_Window. It has methods for -setting the zoom, the \e x and \e y pan, and the rotation angle -about the \e x and \e y axes. - -You can safely skip this section as long as you realize the CubeView -is a sublass of Fl_Gl_Window and will respond to calls from -CubeViewUI, generated by FLUID. - -\par The CubeView Class Definition - -Here is the CubeView class definition, as given by its header file -"test/CubeView.h": - -\code -class CubeView : public Fl_Gl_Window { - public: - CubeView(int x,int y,int w,int h,const char *l=0); - // this value determines the scaling factor used to draw the cube. - double size; - /* Set the rotation about the vertical (y ) axis. - * - * This function is called by the horizontal roller in CubeViewUI - * and the initialize button in CubeViewUI. - */ - void v_angle(float angle){vAng=angle;}; - // Return the rotation about the vertical (y ) axis. - float v_angle(){return vAng;}; - /* Set the rotation about the horizontal (x ) axis. - * - * This function is called by the vertical roller in CubeViewUI - and the - * initialize button in CubeViewUI. - */ - void h_angle(float angle){hAng=angle;}; - // the rotation about the horizontal (x ) axis. - float h_angle(){return hAng;}; - /* Sets the x shift of the cube view camera. - * - * This function is called by the slider in CubeViewUI and the - * initialize button in CubeViewUI. - */ - void panx(float x){xshift=x;}; - /* Sets the y shift of the cube view camera. - * - * This function is called by the slider in CubeViewUI and the - * initialize button in CubeViewUI. - */ - void pany(float y){yshift=y;}; - /* The widget class draw() override. - * The draw() function initialize Gl for another round of - * drawing then calls specialized functions for drawing each - * of the entities displayed in the cube view. - */ - void draw(); - - private: - /* Draw the cube boundaries - * Draw the faces of the cube using the boxv[] vertices, using - * GL_LINE_LOOP for the faces. The color is #defined by - * CUBECOLOR. - */ - void drawCube(); - - float vAng,hAng; float xshift,yshift; - - float boxv0[3];float boxv1[3]; float boxv2[3];float boxv3[3]; - float boxv4[3];float boxv5[3]; float boxv6[3];float boxv7[3]; -}; -\endcode - -\par The CubeView Class Implementation - -Here is the CubeView implementation. It is very similar to the -"cube" demo included with FLTK. - -\code -#include "CubeView.h" -#include <math.h> - -CubeView::CubeView(int x,int y,int w,int h,const char *l) - : Fl_Gl_Window(x,y,w,h,l) -{ - vAng = 0.0; hAng=0.0; size=10.0; - /* The cube definition. These are the vertices of a unit cube - * centered on the origin.*/ - boxv0[0] = -0.5; boxv0[1] = -0.5; boxv0[2] = -0.5; boxv1[0] = 0.5; - boxv1[1] = -0.5; boxv1[2] = -0.5; boxv2[0] = 0.5; boxv2[1] = 0.5; - boxv2[2] = -0.5; boxv3[0] = -0.5; boxv3[1] = 0.5; boxv3[2] = -0.5; - boxv4[0] = -0.5; boxv4[1] = -0.5; boxv4[2] = 0.5; boxv5[0] = 0.5; - boxv5[1] = -0.5; boxv5[2] = 0.5; boxv6[0] = 0.5; boxv6[1] = 0.5; - boxv6[2] = 0.5; boxv7[0] = -0.5; boxv7[1] = 0.5; boxv7[2] = 0.5; -}; - -// The color used for the edges of the bounding cube. -#define CUBECOLOR 255,255,255,255 - -void CubeView::drawCube() { -/* Draw a colored cube */ -#define ALPHA 0.5 - glShadeModel(GL_FLAT); - - glBegin(GL_QUADS); - glColor4f(0.0, 0.0, 1.0, ALPHA); - glVertex3fv(boxv0); - glVertex3fv(boxv1); - glVertex3fv(boxv2); - glVertex3fv(boxv3); - - glColor4f(1.0, 1.0, 0.0, ALPHA); - glVertex3fv(boxv0); - glVertex3fv(boxv4); - glVertex3fv(boxv5); - glVertex3fv(boxv1); - - glColor4f(0.0, 1.0, 1.0, ALPHA); - glVertex3fv(boxv2); - glVertex3fv(boxv6); - glVertex3fv(boxv7); - glVertex3fv(boxv3); - - glColor4f(1.0, 0.0, 0.0, ALPHA); - glVertex3fv(boxv4); - glVertex3fv(boxv5); - glVertex3fv(boxv6); - glVertex3fv(boxv7); - - glColor4f(1.0, 0.0, 1.0, ALPHA); - glVertex3fv(boxv0); - glVertex3fv(boxv3); - glVertex3fv(boxv7); - glVertex3fv(boxv4); - - glColor4f(0.0, 1.0, 0.0, ALPHA); - glVertex3fv(boxv1); - glVertex3fv(boxv5); - glVertex3fv(boxv6); - glVertex3fv(boxv2); - glEnd(); - - glColor3f(1.0, 1.0, 1.0); - glBegin(GL_LINES); - glVertex3fv(boxv0); - glVertex3fv(boxv1); - - glVertex3fv(boxv1); - glVertex3fv(boxv2); - - glVertex3fv(boxv2); - glVertex3fv(boxv3); - - glVertex3fv(boxv3); - glVertex3fv(boxv0); - - glVertex3fv(boxv4); - glVertex3fv(boxv5); - - glVertex3fv(boxv5); - glVertex3fv(boxv6); - - glVertex3fv(boxv6); - glVertex3fv(boxv7); - - glVertex3fv(boxv7); - glVertex3fv(boxv4); - - glVertex3fv(boxv0); - glVertex3fv(boxv4); - - glVertex3fv(boxv1); - glVertex3fv(boxv5); - - glVertex3fv(boxv2); - glVertex3fv(boxv6); - - glVertex3fv(boxv3); - glVertex3fv(boxv7); - glEnd(); -};//drawCube - -void CubeView::draw() { - if (!valid()) { - glLoadIdentity(); glViewport(0,0,w(),h()); - glOrtho(-10,10,-10,10,-20000,10000); glEnable(GL_BLEND); - glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA); - } - - glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); - glPushMatrix(); glTranslatef(xshift, yshift, 0); - glRotatef(hAng,0,1,0); glRotatef(vAng,1,0,0); - glScalef(float(size),float(size),float(size)); drawCube(); - glPopMatrix(); -}; -\endcode - -\subsection fluid_cubevieui The CubeViewUI Class - -We will completely construct a window to display and control the -CubeView defined in the previous section using FLUID. - -\par Defining the CubeViewUI Class - -Once you have started FLUID, the first step in defining a class is to -create a new class within FLUID using the <b>New->Code->Class</b> -menu item. Name the class "CubeViewUI" and leave the -subclass blank. We do not need any inheritance for this -window. You should see the new class declaration in the FLUID -browser window. - -\image html fluid1.png "Figure 9-3: FLUID file for CubeView" -\image latex fluid1.png "FLUID file for CubeView" width=10cm - -\par Adding the Class Constructor - -Click on the CubeViewUI class in the FLUID window and add a new method -by selecting <b>New->Code->Function/Method.</b> The name of the -function will also be CubeViewUI. FLUID will understands that this will -be the constructor for the class and will generate the appropriate -code. Make sure you declare the constructor public. - -Then add a window to the CubeViewUI class. Highlight the name of -the constructor in the FLUID browser window and click on -<b>New->Group->Window</b>. In a similar manner add the -following to the CubeViewUI constructor: - -\li A horizontal roller named \p hrot -\li A vertical roller named \p vrot -\li A horizontal slider named \p xpan -\li A vertical slider named \p ypan -\li A horizontal value slider named \p zoom - -None of these additions need be public. And they shouldn't be -unless you plan to expose them as part of the interface for -CubeViewUI. - -When you are finished you should have something like this: - -\image html fluid2.png "Figure 9-4: FLUID window containing CubeView demo" -\image latex fluid2.png "FLUID window containing CubeView demo" width=10cm - -We will talk about the \p show() method that is highlighted -shortly. - -\par Adding the CubeView Widget - -What we have is nice, but does little to show our cube. We have already -defined the CubeView class and we would like to show it within the -CubeViewUI. - -The CubeView class inherits the Fl_Gl_Window class, which -is created in the same way as a Fl_Box widget. Use -<b>New->Other->Box</b> to add a square box to the main window. -This will be no ordinary box, however. - -The Box properties window will appear. The key to letting CubeViewUI -display CubeView is to enter CubeView in the <b>Class:</b> text -entry box. This tells FLUID that it is not an Fl_Box, but a -similar widget with the same constructor. - -In the <b>Extra Code:</b> field enter <tt>\#include "CubeView.h"</tt> - -This \p \#include is important, as we have just included -CubeView as a member of CubeViewUI, so any public CubeView methods are -now available to CubeViewUI. - -\image html fluid3-cxx.png "Figure 9-5: CubeView methods" -\image latex fluid3-cxx.png "CubeView methods" width=10cm - -\par Defining the Callbacks - -Each of the widgets we defined before adding CubeView can have -callbacks that call CubeView methods. You can call an external -function or put in a short amount of code in the <b>Callback</b> -field of the widget panel. For example, the callback for the -\p ypan slider is: - -\code -cube->pany(((Fl_Slider *)o)->value()); -cube->redraw(); -\endcode - -We call <tt>cube->redraw()</tt> after changing the value to update -the CubeView window. CubeView could easily be modified to do this, but -it is nice to keep this exposed in the case where you may want to do -more than one view change only redrawing once saves a lot of time. - -There is no reason no wait until after you have added CubeView to -enter these callbacks. FLUID assumes you are smart enough not to refer -to members or functions that don't exist. - -\par Adding a Class Method - -You can add class methods within FLUID that have nothing to do with the -GUI. An an example add a show function so that CubeViewUI can actually -appear on the screen. - -Make sure the top level CubeViewUI is selected and select -<b>New->Code->Function/Method</b>. Just use the name -\p show(). We don't need a return value here, and since we will -not be adding any widgets to this method FLUID will assign it a return -type of \p void. - -\image html fluid4.png "Figure 9-6: CubeView constructor" -\image latex fluid4.png "CubeView constructor" width=10cm - -Once the new method has been added, highlight its name and select -<b>New->Code->Code.</b> Enter the method's code in the code window. - -\subsection fluid_addconst Adding Constructor Initialization Code - -If you need to add code to initialize class, for example setting -initial values of the horizontal and vertical angles in the -CubeView, you can simply highlight the Constructor and select -<b>New->Code->Code</b>. Add any required code. - -\subsection fluid_gencode Generating the Code - -Now that we have completely defined the CubeViewUI, we have to generate -the code. There is one last trick to ensure this all works. Open the -preferences dialog from <b>Edit->Preferences</b>. - -At the bottom of the preferences dialog box is the key: -<b>"Include Header from Code"</b>. -Select that option and set your desired file -extensions and you are in business. You can include the CubeViewUI.h -(or whatever extension you prefer) as you would any other C++ class. - -<!-- NEW PAGE --> - -\section fluid_references FLUID Reference - -The following sections describe each of the windows in FLUID. - -\subsection fluid_browser The Widget Browser - -The main window shows a menu bar and a scrolling browser of -all the defined widgets. The name of the <tt>.fl</tt> 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. -The leftmost widgets are the \e parents, and all the widgets -listed below them are their \e children. Parents don't have to have -any children. - -The top level of the hierarchy is composed of \e functions and -\e classes. Each of these will produce a single C++ public -function or class in the output <tt>.cxx</tt> file. Calling the function or -instantiating the class will create all of the child widgets. - -The second level of the hierarchy contains the \e windows. -Each of these produces an instance of class Fl_Window. - -Below that are either \e widgets (subclasses of Fl_Widget) or -\e groups of widgets (including other groups). Plain groups are for -layout, navigation, and resize purposes. <i>Tab groups</i> provide the -well-known file-card tab interface. - -Widgets are shown in the browser by either their \e name (such -as "main_panel" in the example), or by their \e type -and \e label (such as "Button "the green""). - -You \e 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. Note that hidden children may -be selected even when there is no visual indication of this. - -You \e open widgets by double-clicking on them, or (to open several -widgets you have picked) by typing the F1 key. A control panel will appear -so you can change the widget(s). - -\subsection fluid_menu_items 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: - -\par File/Open... (Ctrl+o) - -\par -Discards the current editing session and reads in a different -<tt>.fl</tt> file. You are asked for confirmation if you have -changed the current file. - -\par -FLUID can also read <tt>.fd</tt> files produced by the Forms -and XForms "fdesign" programs. It is best to -File/Merge them instead of opening them. FLUID does not -understand everything in a <tt>.fd</tt> 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 -<tt>.fd</tt> file with its own format, which fdesign cannot -read! - -\par File/Insert... (Ctrl+i) - -\par -Inserts the contents of another <tt>.fl</tt> file, without -changing the name of the current <tt>.fl</tt> file. All the -functions (even if they have the same names as the current ones) -are added, and you will have to use cut/paste to put the widgets -where you want. - -\par File/Save (Ctrl+s) - -\par -Writes the current data to the <tt>.fl</tt> file. If the -file is unnamed then FLUID will ask for a filename. - -\par File/Save As... (Ctrl+Shift+S) - -\par -Asks for a new filename and saves the file. - -\par File/Write Code (Ctrl+Shift+C) - -\par -"Compiles" the data into a <tt>.cxx</tt> and <tt>.h</tt> -file. These are exactly the same as the files you get when you run -FLUID with the \c -c switch. - -\par -The output file names are the same as the <tt>.fl</tt> file, with -the leading directory and trailing ".fl" stripped, and -".h" or ".cxx" appended. - -\par File/Write Strings (Ctrl+Shift+W) - -\par -Writes a message file for all of the text labels defined in -the current file. - -\par -The output file name is the same as the <tt>.fl</tt> file, -with the leading directory and trailing ".fl" -stripped, and ".txt", ".po", or ".msg" appended depending on the -\ref fluid_i18n "Internationalization Mode". - -\par File/Quit (Ctrl+q) - -\par -Exits FLUID. You are asked for confirmation if you have -changed the current file. - -\par Edit/Undo (Ctrl+z) - -\par -This isn't implemented yet. You should do save often so you can -recover from any mistakes you make. - -\par Edit/Cut (Ctrl+x) - -\par -Deletes the selected widgets and all of their children. -These are saved to a "clipboard" file and can be -pasted back into any FLUID window. - -\par Edit/Copy (Ctrl+c) - -\par -Copies the selected widgets and all of their children to the -"clipboard" file. - -\par Edit/Paste (Ctrl+c) - -\par -Pastes the widgets from the clipboard file. - -\par -If the widget is a window, it is added to whatever function -is selected, or contained in the current selection. - -\par -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. - -\par -To avoid confusion, it is best to select exactly one widget -before doing a paste. - -\par -Cut/paste is the only way to change the parent of a -widget. - -\par Edit/Select All (Ctrl+a) - -\par -Selects all widgets in the same group as the current selection. - -\par -If they are all selected already then this selects all -widgets in that group's parent. Repeatedly typing Ctrl+a will -select larger and larger groups of widgets until everything is -selected. - -\par Edit/Open... (F1 or double click) - -\par -Displays the current widget in the attributes panel. If the -widget is a window and it is not visible then the window is -shown instead. - -\par Edit/Sort - -\par -Sorts the selected widgets 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. - -\par Edit/Earlier (F2) - -\par -Moves all of the selected widgets one earlier in order among -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, classes, and -windows within functions. - -\par Edit/Later (F3) - -\par -Moves all of the selected widgets one later in order among -the children of their parent (if possible). - -\par Edit/Group (F7) - -\par -Creates a new Fl_Group and make all the currently -selected widgets children of it. - -\par Edit/Ungroup (F8) - -\par -Deletes the parent group if all the children of a group are -selected. - -\par Edit/Overlays on/off (Ctrl+Shift+O) - -\par -Toggles 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. - -\par Edit/Project Settings... (Ctrl+p) - -\par -Displays the project settings panel. -The output filenames control the extensions or names of the -files the are generated by FLUID. If you check the "Include .h -from .cxx" button the code file will include the header file -automatically. - -\par -The \ref fluid_i18n "internationalization" options are described -later in this chapter. - -\image html fluid_prefs.png "Figure 9-7: FLUID Preferences Window" -\image latex fluid_prefs.png "FLUID Preferences Window" width=10cm - -\par Edit/GUI Settings... (Shift+Ctrl+p) - -\par -Displays the GUI settings panel. This panel is used -to control the user interface settings. - -\par New/Code/Function - -\par -Creates 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 which -can be referred to by code you type into the individual widgets. - -\par -If the function contains any unnamed windows, it will be -declared as returning a Fl_Window pointer. 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 nothing (\c void ). - -\par -It is possible to make the <tt>.cxx</tt> output be a -self-contained program that can be compiled and executed. This -is done by deleting the function name so -\p main(argc,argv) is used. The function will call -\p show() on all the windows it creates and then call -\p Fl::run(). This can also be used to test resize -behavior or other parts of the user interface. - -\par -You can change the function name by double-clicking on the -function. - -\par New/Window - -\par -Creates a new Fl_Window widget. The window is added -to the currently selected function, or to the function -containing the currently selected item. The window will appear, -sized to 100x100. You can resize it to whatever size you -require. - -\par -The widget panel will also appear and is described later in -this chapter. - -\par New/... - -\par -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. - -\par -When you create the widget you will get the widget's control -panel, which is described later in this chapter. - -\par Layout/Align/... - -\par -Align all selected widgets to the first widget in the selection. - -\par Layout/Space Evenly/... - -\par -Space all selected widgets evenly inside the selected space. -Widgets will be sorted from first to last. - -\par Layout/Make Same Size/... - -\par -Make all selected widgets the same size as the first selected widget. - -\par Layout/Center in Group/... - -\par -Center all selected widgets relative to their parent widget - -\par Layout/Grid... (Ctrl+g) - -\par -Displays the grid settings panel. -This panel -controls the grid that all widgets snap to when you move and -resize them, and for the "snap" which is how far a widget has to -be dragged from its original position to actually change. - -\par Shell/Execute Command... (Alt+x) - -\par -Displays the shell command panel. The shell command -is commonly used to run a 'make' script to compile the FLTK output. - -\par Shell/Execute Again (Alt+g) - -\par -Run the shell command again. - -\par Help/About FLUID - -\par -Pops up a panel showing the version of FLUID. - -\par Help/On FLUID - -\par -Shows this chapter of the manual. - -\par Help/Manual - -\par -Shows the contents page of the manual - -\subsection fluid_widget_panel The Widget Panel - -When you double-click on 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 Ctrl+Shift+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 \e one of -the widgets is shown. But if you change this value, \e all -of 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 such as mismatched -parenthesis in any code 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 are -undone, however. - -<!-- NEW PAGE --> - -\image html fluid_widget_gui.png "Figure 9-8: The FLUID widget GUI attributes" -\image latex fluid_widget_gui.png "The FLUID widget GUI attributes" width=10cm - -\section fluid_widget_attributes GUI Attributes - -\par Label (text field) - -\par -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. - -\par -\ref common_labels "Symbols" -can be added to the label using the at sign ("@"). - -\par Label (pull down menu) - -\par -How to draw the label. Normal, shadowed, engraved, and -embossed change the appearance of the text. - -\par Image - -\par -The active image for the widget. Click on the -\b Browse... button to pick an image file using the file -chooser. - -\par Inactive - -\par -The inactive image for the widget. Click on the -\b Browse... button to pick an image file using the file -chooser. - -\par Alignment (buttons) - -\par -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. - -\par -The \b clip button clips the label to the widget box, the -\b wrap button wraps any text in the label, and the -<b>text image</b> button puts the text over the image instead of under -the image. - -\par Position (text fields) - -\par -The position fields show the current position and size of the -widget box. Enter new values to move and/or resize a widget. - -\par Values (text fields) - -\par -The values and limits of the current widget. Depending on the -type of widget, some or all of these fields may be inactive. - -\par Shortcut - -\par -The shortcut key to activate the widget. Click on the -shortcut button and press any key sequence to set the shortcut. - -\par Attributes (buttons) - -\par -The \b Visible button controls whether the widget is -visible (on) or hidden (off) initially. Don't change this for -windows or for the immediate children of a Tabs group. - -\par -The \b Active button controls whether the widget is -activated (on) or deactivated (off) initially. Most widgets -appear greyed out when deactivated. - -\par -The \b Resizable button controls whether the window is -resizeable. 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. You can get more complex -behavior by making invisible boxes the resizable widget, or by -using hierarchies of groups. Unfortunately the only way to test -it is to compile the program. Resizing the FLUID window is -\e not the same as what will happen in the user program. - -\par -The \b Hotspot button causes the parent window to be -positioned with that widget centered on the mouse. This -position is determined <i>when the FLUID function is called</i>, -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 -\p show(). - -\par -The \b Border 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. - -\par X Class (text field) - -\par -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 html fluid_widget_style.png "Figure 9-9: The FLUID widget Style attributes" -\image latex fluid_widget_style.png "The FLUID widget Style attributes" width=10cm - -\subsection fluid_style_attributes Style Attributes - -\par Label Font (pulldown menu) - -\par -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. - -\par Label Size (pulldown menu) - -\par -Pixel size (height) 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. - -\par Label Color (button) - -\par -Color to draw the label. Ignored by pixmaps (bitmaps, -however, do use this color as the foreground color). - -\par Box (pulldown menu) - -\par -The boxtype to draw as a background for the widget. - -\par -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 may leave unwanted stuff inside the widget. - -\par -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. Note that this -checkerboard is not drawn by the resulting program. Instead -random garbage will be displayed. - -\par Down Box (pulldown menu) - -\par -The boxtype to draw when a button is pressed or for some -parts of other widgets like scrollbars and valuators. - -\par Color (button) - -\par -The color to draw the box with. - -\par Select Color (button) - -\par -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. - -\par Text Font, Size, and Color - -\par -Some widgets display text, such as input fields, pull-down -menus, and browsers. - -\image html fluid_widget_cxx.png "Figure 9-10: The FLUID widget C++ attributes" -\image latex fluid_widget_cxx.png "The FLUID widget C++ attributes" width=10cm - -\subsection fluid_cpp_attributes C++ Attributes - -\par Class - -\par -This is how you use your own subclasses of -Fl_Widget. Whatever identifier you type in here will -be the class that is instantiated. - -\par -In addition, no \p \#include header file is put in the -<tt>.h</tt> file. You must provide a \p \#include line as -the first line of the "Extra Code" which declares your -subclass. - -\par -The class must 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 -\code #include <FL/Fl_Double_Window.h> \endcode -to the extra code. - -\par Type (upper-right pulldown menu) - -\par -Some classes have subtypes that modify their appearance or behavior. -You pick the subtype off of this menu. - -\par Name (text field) - -\par -Name of a 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. - -\par -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. - -\par Public (button) - -\par -Controls whether the widget is publicly accessible. When -embedding widgets in a C++ class, this controls whether the -widget is \p public or \p private in the class. -Otherwise is controls whether the widget is declared -\p static or global (\p extern ). - -\par Extra Code (text fields) - -\par -These four fields let you type in literal lines of code to -dump into the <tt>.h</tt> or <tt>.cxx</tt> files. - -\par -If the text starts with a <tt>\#</tt> or the word -\p extern then FLUID thinks this is an "include" -line, and it is written to the <tt>.h</tt> file. If the same -include line occurs several times then only one copy is -written. - -\par -All other lines are "code" lines. The current -widget is pointed to by the local variable \p o. The -window being constructed is pointed to by the local variable -\p w. You can also access any arguments passed to the -function here, and any named widgets that are before this -one. - -\par -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 four lines you -probably should call a function in your own <tt>.cxx</tt> -code. - -\par Callback (text field) - -\par -This can either be the name of a function, or a small snippet -of code. If you enter anything other than letters, numbers, and the -underscore then FLUID treats it as code. - -\par -A name refers to a function in your own code. It must be -declared as <tt>void name(<class>*,void*)</tt>. - -\par -A code snippet is inserted into a static function in the -<tt>.cxx</tt> output file. The function prototype is -<tt>void name(class *o, void *v)</tt> -so that you can refer to the widget as \p o and the \p user_data() -as \p 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. - -\par -If the callback is blank then no callback is set. - -\par User Data (text field) - -\par -This is a value for the \p 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 cast to a \p void pointer. - -\par Type (text field) - -\par -The \p void* in the callback function prototypes is -replaced with this. You may want to use \p long for old -XForms code. Be warned that anything other than \p void* -is not guaranteed to work! However on most architectures other -pointer types are ok, and \p long is usually ok, too. - -\par When (pulldown menu) - -\par -When to do the callback. This can be \b Never, -\b Changed, \b Release, or \b Enter Key. The value of -<b>Enter Key</b> is only useful for text input fields. - -\par -There are other rare but useful values for the -\p when() field that are not in the menu. You should use -the extra code fields to put these values in. - -\par No Change (button) - -\par -The <b>No Change</b> button means the callback is done on the -matching event even if the data is not changed. - -\section fluid_selecting_moving Selecting and 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 \c 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 Ctrl+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: - -\section fluid_images Image Labels - -The \e contents of the image files in the \b Image -and \b Inactive text fields are written to the <tt>.cxx</tt> -file. If many widgets share the same image then only one copy is -written. Since the image data is embedded in the generated -source code, you need only distribute the C++ code and not the -image files themselves. - -However, the \e filenames are stored in the <tt>.fl</tt> -file so you will need the image files as well to read the -<tt>.fl</tt> file. Filenames are relative to the location of the -<tt>.fl</tt> file and not necessarily the current directory. We -recommend you either put the images in the same directory as the -<tt>.fl</tt> file, or use absolute path names. - -\par Notes for All Image Types - -\par -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. - -\par -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. - -\par -If you edit an image at the same time you are using it in FLUID, -the only way to convince FLUID to read the image file again is to -remove the image from all widgets that are using it or re-load the -<tt>.fl</tt> file. - -\par -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. - -\par -To more accurately place images, make a new "box" -widget and put the image in that as the label. - -\par XBM (X Bitmap) Files - -\par -FLUID reads X bitmap files which use C source code to define -a bitmap. Sometimes they are stored with the ".h" or -".bm" extension rather than the standard -".xbm" extension. - -\par -FLUID writes code to construct an Fl_Bitmap image 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 this color in the -FLUID widget attributes panel. The '0' bits are transparent. - -\par -The program "bitmap" on the X distribution does an -adequate job of editing bitmaps. - -\par XPM (X Pixmap) Files - -\par -FLUID reads X pixmap files as used by the \p libxpm -library. These files use C source code to define a pixmap. The -filenames usually have the ".xpm" extension. - -\par -FLUID writes code to construct an Fl_Pixmap image 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, and FLTK uses this -information to generate a transparency mask for the image. - -\par -We have not found any good editors for small iconic pictures. -For pixmaps we have used -<A href="http://home.worldonline.dk/~torsten/xpaint/index.html">XPaint</A> -and the KDE icon editor. - -\par BMP Files - -\par -FLUID reads Windows BMP image files which are often used in -WIN32 applications for icons. FLUID converts BMP files into -(modified) XPM format and uses a Fl_BMP_Image image to label the -widget. Transparency is handled the same as for XPM files. All -image data is uncompressed when written to the source file, so -the code may be much bigger than the <tt>.bmp</tt> file. - -\par GIF Files - -\par -FLUID reads GIF image files which are often used in HTML -documents to make icons. FLUID converts GIF files into -(modified) XPM format and uses a Fl_GIF_Image image to label the -widget. Transparency is handled the same as for XPM files. All -image data is uncompressed when written to the source file, so -the code may be much bigger than the <tt>.gif</tt> file. Only -the first image of an animated GIF file is used. - -\par JPEG Files - -\par -If FLTK is compiled with JPEG support, FLUID can read JPEG -image files which are often used for digital photos. FLUID uses -a Fl_JPEG_Image image to label the widget, and writes -uncompressed RGB or grayscale data to the source file. - -\par PNG (Portable Network Graphics) Files - -\par -If FLTK is compiled with PNG support, FLUID can read PNG -image files which are often used in HTML documents. FLUID uses a -Fl_PNG_Image image to label the widget, and writes uncompressed -RGB or grayscale data to the source file. PNG images can provide -a full alpha channel for partial transparency, and FLTK supports -this as best as possible on each platform. - -\section fluid_i18n Internationalization with FLUID - -FLUID supports internationalization (I18N for short) of label -strings used by widgets. The preferences window -(<tt>Ctrl+p</tt>) provides access to the I18N options. - -\subsection fluid_i18n_methods I18N Methods - -FLUID supports three methods of I18N: use none, use GNU -gettext, and use POSIX catgets. The "use none" method is the -default and just passes the label strings as-is to the widget -constructors. - -The "GNU gettext" method uses GNU gettext (or a similar -text-based I18N library) to retrieve a localized string before -calling the widget constructor. - -The "POSIX catgets" method uses the POSIX catgets function to -retrieve a numbered message from a message catalog before -calling the widget constructor. - -\subsection fluid_gettext_i18n Using GNU gettext for I18N - -FLUID's code support for GNU gettext is limited to calling a -function or macro to retrieve the localized label; you still -need to call \p setlocale() and \p textdomain() or -\p bindtextdomain() to select the appropriate language and -message file. - -To use GNU gettext for I18N, open the preferences window and -choose "GNU gettext" from the \b Use: chooser. Two new input -fields will then appear to control the include file and -function/macro name to use when retrieving the localized label -strings. - - \image html fluid-gettext.png "Figure 9-11: Internationalization using GNU gettext" - \image latex fluid-gettext.png "Internationalization using GNU gettext" width=10cm - -The \b \#include -field controls the header file to include for -I18N; by default this is \b <libintl.h>, the -standard I18N file for GNU gettext. - -The \b Function: field controls the function (or macro) that -will retrieve the localized message; by default the -\p gettext function will be called. - -\subsection fluid_catgets_i18n Using POSIX catgets for I18N - -FLUID's code support for POSIX catgets allows you to use a -global message file for all interfaces or a file specific to -each <tt>.fl</tt> file; you still need to call -\p setlocale() to select the appropriate language. - -To use POSIX catgets for I18N, open the preferences window -and choose "POSIX catgets" from the \b Use: chooser. Three new -input fields will then appear to control the include file, -catalog file, and set number for retrieving the localized label -strings. - - \image html fluid-catgets.png "Figure 9-12: Internationalization using POSIX catgets" - \image latex fluid-catgets.png "Internationalization using POSIX catgets" width=10cm - -The \b \#include -field controls the header file to include for -I18N; by default this is \b <nl_types.h>, the -standard I18N file for POSIX catgets. - -The \b File: field controls the name of the catalog file -variable to use when retrieving localized messages; by default -the file field is empty which forces a local (static) catalog -file to be used for all of the windows defined in your -<tt>.fl</tt> file. - -The \b Set: field controls the set number in the catalog file. -The default set is 1 and rarely needs to be changed. - -\section fluid_limitations Known limitations - -Declaration Blocks can be used to temporarily block out already -designed code using <tt>\#if 0</tt> and <tt>\#endif</tt> -type construction. This will effectively avoid compilation of -blocks of code. However, static code and data generated by this -segment (menu items, images, include statements, etc.) will still -be generated and likely cause compile-time warnings. - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="opengl.html"> - [Prev] - Using OpenGL - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="advanced.html"> - Advanced FLTK - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/fluid.man b/branch-3.0-2011/documentation/src/fluid.man deleted file mode 100644 index cb6849bc3..000000000 --- a/branch-3.0-2011/documentation/src/fluid.man +++ /dev/null @@ -1,32 +0,0 @@ -.TH fluid 1 "Fast Light Tool Kit" "6 January 2002" -.SH NAME -fluid \- the fast light user-interface designer -.sp -.SH SYNOPSIS -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 -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. -.SH SEE ALSO -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/branch-3.0-2011/documentation/src/fluid1.png b/branch-3.0-2011/documentation/src/fluid1.png Binary files differdeleted file mode 100644 index 1c7909f6f..000000000 --- a/branch-3.0-2011/documentation/src/fluid1.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fluid2.png b/branch-3.0-2011/documentation/src/fluid2.png Binary files differdeleted file mode 100644 index d8d7e3a80..000000000 --- a/branch-3.0-2011/documentation/src/fluid2.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fluid3-cxx.png b/branch-3.0-2011/documentation/src/fluid3-cxx.png Binary files differdeleted file mode 100644 index ea148279d..000000000 --- a/branch-3.0-2011/documentation/src/fluid3-cxx.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fluid3-gui.png b/branch-3.0-2011/documentation/src/fluid3-gui.png Binary files differdeleted file mode 100644 index 6d817c9fe..000000000 --- a/branch-3.0-2011/documentation/src/fluid3-gui.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fluid3-style.png b/branch-3.0-2011/documentation/src/fluid3-style.png Binary files differdeleted file mode 100644 index 200e40285..000000000 --- a/branch-3.0-2011/documentation/src/fluid3-style.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fluid4.png b/branch-3.0-2011/documentation/src/fluid4.png Binary files differdeleted file mode 100644 index f2aba97db..000000000 --- a/branch-3.0-2011/documentation/src/fluid4.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fluid_prefs.png b/branch-3.0-2011/documentation/src/fluid_prefs.png Binary files differdeleted file mode 100644 index 7d7048061..000000000 --- a/branch-3.0-2011/documentation/src/fluid_prefs.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fluid_widget_cxx.png b/branch-3.0-2011/documentation/src/fluid_widget_cxx.png Binary files differdeleted file mode 100644 index ff6085620..000000000 --- a/branch-3.0-2011/documentation/src/fluid_widget_cxx.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fluid_widget_gui.png b/branch-3.0-2011/documentation/src/fluid_widget_gui.png Binary files differdeleted file mode 100644 index e0e6f73ed..000000000 --- a/branch-3.0-2011/documentation/src/fluid_widget_gui.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/fluid_widget_style.png b/branch-3.0-2011/documentation/src/fluid_widget_style.png Binary files differdeleted file mode 100644 index 78d869a7f..000000000 --- a/branch-3.0-2011/documentation/src/fluid_widget_style.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/forms.dox b/branch-3.0-2011/documentation/src/forms.dox deleted file mode 100644 index ef135981f..000000000 --- a/branch-3.0-2011/documentation/src/forms.dox +++ /dev/null @@ -1,273 +0,0 @@ -/** - <!-- Warning: \p .fd does not work but <tt>.fd</tt> does --> - - \page forms Forms Compatibility - -This appendix describes the Forms compatibility included with FLTK. - -<center> -<table border="1" width="90%" bgcolor="#cccccc"> -<tr> -<th align="center"> -Warning: The Forms compatility is deprecated and no longer maintained in FLTK1, -and is likely to be removed completely after the next official release. -</th> -</tr> -</table> -</center> - -\section forms_importing Importing Forms Layout Files - -\ref fluid "FLUID" -can read the <tt>.fd</tt> 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>. - -\section forms_using 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 -\c forms.h file supplied with FLTK is included. -The \c forms.h file simply pulls in <FL/forms.H> so you don't need to -change your source code. -Take a look at <FL/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 compatible 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 <tt>forms.H</tt> a lot. - -\section forms_problems Problems You Will Encounter - -Many parts of XForms use X-specific structures like \c 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 \e old Forms "free" widget. -It may be useful for porting programs that change the \c 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(). - -<I>All instance variables are hidden.</I> If you directly refer to -the \p x, \p y, \p w, \p h, \p 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 <tt>"->x"</tt> -with <tt>"->x()"</tt>, etc. -Replace <tt>"boxtype"</tt> with <tt>"box()"</tt>. - -<tt>const char *</tt> arguments to most FLTK methods are simply -stored, while Forms would \c 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 -\c 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 \c user_data() -field of a window. To do this, search through the fdesign output for all -occurances of <tt>"->fdui"</tt> and edit to use <tt>"->user_data()"</tt> -instead. This will require casts and is not trivial. - -The prototype for the functions passed to \c fl_add_timeout() -and \c fl_set_idle_callback() callback are different. - -<B>All the following XForms calls are missing:</B> - -\li \c FL_REVISION, \c fl_library_version() -\li \c FL_RETURN_DBLCLICK (use Fl::event_clicks()) -\li \c fl_add_signal_callback() -\li \c fl_set_form_atactivate() \c fl_set_form_atdeactivate() -\li \c fl_set_form_property() -\li \c fl_set_app_mainform(), \c fl_get_app_mainform() -\li \c fl_set_form_minsize(), \c fl_set_form_maxsize() -\li \c fl_set_form_event_cmask(), \c fl_get_form_event_cmask() -\li \c fl_set_form_dblbuffer(), \c fl_set_object_dblbuffer() - (use an Fl_Double_Window instead) -\li \c fl_adjust_form_size() -\li \c fl_register_raw_callback() -\li \c fl_set_object_bw(), \c fl_set_border_width() -\li \c fl_set_object_resize(), \c fl_set_object_gravity() -\li \c fl_set_object_shortcutkey() -\li \c fl_set_object_automatic() -\li \c fl_get_object_bbox() (maybe FLTK should do this) -\li \c fl_set_object_prehandler(), \c fl_set_object_posthandler() -\li \c fl_enumerate_fonts() -\li Most drawing functions -\li \c fl_set_coordunit() (FLTK uses pixels all the time) -\li \c fl_ringbell() -\li \c fl_gettime() -\li \c fl_win*() (all these functions) -\li \c fl_initialize(argc,argv,x,y,z) ignores last 3 arguments -\li \c fl_read_bitmapfile(), \c fl_read_pixmapfile() -\li \c fl_addto_browser_chars() -\li \c FL_MENU_BUTTON just draws normally -\li \c fl_set_bitmapbutton_file(), \c fl_set_pixmapbutton_file() -\li \c FL_CANVAS objects -\li \c FL_DIGITAL_CLOCK (comes out analog) -\li \c fl_create_bitmap_cursor(), \c fl_set_cursor_color() -\li \c fl_set_dial_angles() -\li \c fl_show_oneliner() -\li \c fl_set_choice_shortcut(a,b,c) -\li command log -\li Only some of file selector is emulated -\li \c FL_DATE_INPUT -\li \c fl_pup*() (all these functions) -\li textbox object (should be easy but I had no sample programs) -\li xyplot object - -\section forms_notes 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: - -\par 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. - -\par 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 \c draw() method -and \c 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 -\c draw_overlay() method and call \c redraw_overlay() on the -OpenGL window. - -One easy way to hack your program so it works is to make the \c draw() -and \c 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 \c fl_queue. - -\par 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. - -\par You Cannot Make Forms Subclasses - -Programs that call \c 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 \c handle() -method is not exactly the same as the \c handle() function of Forms. -Where a Forms \c handle() returned non-zero, your \c handle() must -call \c do_callback(). And your \c 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. - -\par 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: - -<CENTER> -<TABLE border=1 WIDTH=90% summary="Mapping of Forms valuators to FLTK."> -<TR><TH align=center>Forms</TH><TH align=center>FLTK</TH></TR> -<TR><TD>MOUSE_X</TD><TD>Fl::event_x_root()</TD></TR> -<TR><TD>MOUSE_Y</TD><TD>Fl::event_y_root()</TD></TR> -<TR><TD>LEFTSHIFTKEY,RIGHTSHIFTKEY</TD><TD>Fl::event_shift()</TD></TR> -<TR><TD>CAPSLOCKKEY</TD><TD>Fl::event_capslock()</TD></TR> -<TR><TD>LEFTCTRLKEY,RIGHTCTRLKEY</TD><TD>Fl::event_ctrl()</TD></TR> -<TR><TD>LEFTALTKEY,RIGHTALTKEY</TD><TD>Fl::event_alt()</TD></TR> -<TR><TD>MOUSE1,RIGHTMOUSE</TD><TD>Fl::event_state()</TD></TR> -<TR><TD>MOUSE2,MIDDLEMOUSE</TD><TD>Fl::event_state()</TD></TR> -<TR><TD>MOUSE3,LEFTMOUSE</TD><TD>Fl::event_state()</TD></TR> -</TABLE> -</CENTER> - -Anything else in \c getvaluator and you are on your own... - -\par 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: - -\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*"); -\endcode - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="glut.html"> - [Prev] - GLUT Compatibility - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="osissues.html"> - Operating System Issues - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/glut.dox b/branch-3.0-2011/documentation/src/glut.dox deleted file mode 100644 index 30e8c9fca..000000000 --- a/branch-3.0-2011/documentation/src/glut.dox +++ /dev/null @@ -1,253 +0,0 @@ -/** - - \page glut GLUT Compatibility - -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 -\c <FL/glut.H> instead of \c <GL/glut.h>. This can be -done by editing the source, by changing the \c -I switches to -the compiler, or by providing a symbolic link from \c GL/glut.h -to \c FL/glut.H. - -<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 \c FL/glut.H -is inline functions. You should take a look at it (and maybe at -\c test/glpuzzle.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 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 \p glutGet(GLUT_ELAPSED_TIME) -\li \p glutGet(GLUT_SCREEN_HEIGHT_MM) -\li \p glutGet(GLUT_SCREEN_WIDTH_MM) -\li \p glutGet(GLUT_WINDOW_NUM_CHILDREN) -\li \p glutInitDisplayMode(GLUT_LUMINANCE) -\li \p glutLayerGet(GLUT_HAS_OVERLAY) -\li \p glutLayerGet(GLUT_LAYER_IN_USE) -\li \p glutPushWindow() -\li \p glutSetColor(), \p glutGetColor(), \p glutCopyColormap() -\li \p glutVideoResize() missing. -\li \p glutWarpPointer() -\li \p glutWindowStatusFunc() -\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 -GLUT_DOWN and GLUT_UP, mouse buttons -GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON, GLUT_RIGHT_BUTTON, and -GLUT_KEY_F1 thru GLUT_KEY_F12. - -The strings passed as menu labels are not copied. - -\p glutPostRedisplay() does not work if called from inside a -display function. You must use \p glutIdleFunc() if you want -your display to update continuously. - -\p glutSwapBuffers() does not work from inside a display -function. This is on purpose, because FLTK swaps the buffers for you. - -\p glutUseLayer() does not work well, and should only be used -to initialize transformations inside a resize callback. You should -redraw overlays by using \p glutOverlayDisplayFunc(). - -Overlays are cleared before the overlay display function is called. -\p glutLayerGet(GLUT_OVERLAY_DAMAGED) always returns true for -compatibility with some GLUT overlay programs. You must rewrite your -code so that \p gl_color() is used to choose colors in an -overlay, or you will get random overlay colors. - -\p glutSetCursor(GLUT_CURSOR_FULL_CROSSHAIR) just results in a -small crosshair. - -The fonts used by \p glutBitmapCharacter() and \p glutBitmapWidth() -may be different. - -\p 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"). - -\section glut_mixing 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 -a call to \p show() the window at the point it is created, which means the -Fl_Window parent window must already be shown. - -\li Don't call \p glutInit(). -\li Create your Fl_Window, and any FLTK widgets. Leave a - blank area in the window for your GLUT window. -\li \p show() the Fl_Window. Perhaps call \p show(argc,argv). -\li Call <tt>window->begin()</tt> so that the GLUT window will be - automatically added to it. -\li Use \p glutInitWindowSize() and \p glutInitWindowPosition() - 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 - \p glutCreateWindow()! -\li You can call either \p glutMainLoop(), Fl::run(), - or loop calling Fl::wait() to run the program. - - -\section glut_Fl_Glut_Window class Fl_Glut_Window - -\subsection glut_class_hierarchy Class Hierarchy - -\code -Fl_Gl_Window - | - +----Fl_Glut_Window -\endcode - -\subsection glut_include_files Include Files - -\code -#include <FL/glut.H> -\endcode - -\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 -better into FLTK's method of creating windows. - -The current GLUT window is available in the global variable -\p glut_window. - -<tt>new %Fl_Glut_Window(...)</tt> is the same as -\p glutCreateWindow() except it does not \p show() the window -or make the window current. - -<tt>window->make_current()</tt> is the same as \p glutSetWindow(number). -If the window has not had \p show() called on it yet, some functions -that assumme an OpenGL context will not work. -If you do \p show() the window, call \p make_current() -again to set the context. - -<tt>~Fl_Glut_Window()</tt> is the same as \p glutDestroyWindow(). - -\subsection glut_members Members - -The Fl_Glut_Window 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> - <TH>description</TH> -</TR> -<TR> - <TD>display</TD> - <TD>A pointer to the function to call to draw the normal planes.</TD> -</TR> -<TR> - <TD>entry</TD> - <TD>A pointer to the function to call when the mouse moves into - or out of the window.</TD> -</TR> -<TR> - <TD>keyboard</TD> - <TD>A pointer to the function to call when a regular key is pressed.</TD> -</TR> -<TR> - <TD>menu[3]</TD> - <TD>The menu to post when one of the mouse buttons is pressed.</TD> -</TR> -<TR> - <TD>mouse</TD> - <TD>A pointer to the function to call when a button is pressed or - released.</TD> -</TR> -<TR> - <TD>motion</TD> - <TD>A pointer to the function to call when the mouse is moved with - a button down.</TD> -</TR> -<TR> - <TD>overlaydisplay</TD> - <TD>A pointer to the function to call to draw the overlay planes.</TD> -</TR> -<TR> - <TD>passivemotion</TD> - <TD>A pointer to the function to call when the mouse is moved with - no buttons down.</TD> -</TR> -<TR> - <TD>reshape</TD> - <TD>A pointer to the function to call when the window is resized.</TD> -</TR> -<TR> - <TD>special</TD> - <TD>A pointer to the function to call when a special key is pressed.</TD> -</TR> -<TR> - <TD>visibility</TD> - <TD>A pointer to the function to call when the window is iconified - or restored (made visible.)</TD> -</TR> -</TABLE></CENTER> - -\subsection glut_methods Methods - -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) - -\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. - -virtual Fl_Glut_Window::~Fl_Glut_Window() - -\par -Destroys the GLUT window. - -void Fl_Glut_Window::make_current() - -\par -Switches all drawing functions to the GLUT window. - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="enumerations.html"> - [Prev] - FLTK Enumerations - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="forms.html"> - Forms Compatibility - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/hello.C.png b/branch-3.0-2011/documentation/src/hello.C.png Binary files differdeleted file mode 100644 index 43604e3e6..000000000 --- a/branch-3.0-2011/documentation/src/hello.C.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/html_footer b/branch-3.0-2011/documentation/src/html_footer deleted file mode 100644 index ebcf443a0..000000000 --- a/branch-3.0-2011/documentation/src/html_footer +++ /dev/null @@ -1,9 +0,0 @@ -<hr> -<address><small> -<!-- $datetime. --> -<a href="http://www.fltk.org"><img src="tiny.png" align="bottom" alt="FLTK"></a> -© 1998-2010 by Bill Spitzak and others. -Permission is granted to reproduce this manual or any portion for -any purpose, provided this copyright and permission notice are preserved. -</small></address> -</body></html> diff --git a/branch-3.0-2011/documentation/src/html_stylesheet.css b/branch-3.0-2011/documentation/src/html_stylesheet.css deleted file mode 100644 index 4fcaeb57e..000000000 --- a/branch-3.0-2011/documentation/src/html_stylesheet.css +++ /dev/null @@ -1,447 +0,0 @@ -body, table, div, p, dl { - font-family: Lucida Grande, Verdana, Geneva, Arial, sans-serif; - font-size: 12px; -} - -/* @group Heading Levels */ - -h1 { - text-align: center; - font-size: 150%; -} - -h2 { - font-size: 130%; -} - -h3 { - font-size: 120%; -} - -/* @end */ - -caption { - font-weight: bold; -} - -div.qindex, div.navtab{ - background-color: #e8eef2; - border: 1px solid #84b0c7; - text-align: center; - margin: 2px; - padding: 2px; -} - -div.qindex, div.navpath { - width: 100%; - line-height: 140%; -} - -div.navtab { - margin-right: 15px; -} - -/* @group Link Styling */ - -a { - color: #153788; - font-weight: normal; - text-decoration: none; -} - -.contents a:visited { - color: #1b77c5; -} - -a:hover { - text-decoration: underline; -} - -a.qindex { - font-weight: bold; -} - -a.qindexHL { - font-weight: bold; - background-color: #6666cc; - color: #ffffff; - border: 1px double #9295C2; -} - -.contents a.qindexHL:visited { - color: #ffffff; -} - -a.el { - font-weight: bold; -} - -a.elRef { -} - -a.code { -} - -a.codeRef { -} - -/* @end */ - -dl.el { - margin-left: -1cm; -} - -.fragment { - font-family: monospace, fixed; - font-size: 105%; -} - -pre.fragment { - border: 1px solid #CCCCCC; - background-color: #f5f5f5; - padding: 4px 6px; - margin: 4px 8px 4px 2px; -} - -div.ah { - background-color: black; - font-weight: bold; - color: #ffffff; - margin-bottom: 3px; - margin-top: 3px -} - -div.groupHeader { - margin-left: 16px; - margin-top: 12px; - margin-bottom: 6px; - font-weight: bold; -} - -div.groupText { - margin-left: 16px; - font-style: italic; -} - -body { - background: white; - color: black; - margin-right: 20px; - margin-left: 20px; -} - -td.indexkey { - background-color: #e8eef2; - font-weight: bold; - border: 1px solid #CCCCCC; - margin: 2px 0px 2px 0; - padding: 2px 10px; -} - -td.indexvalue { - background-color: #e8eef2; - border: 1px solid #CCCCCC; - padding: 2px 10px; - margin: 2px 0px; -} - -tr.memlist { - background-color: #f0f0f0; -} - -p.formulaDsp { - text-align: center; -} - -img.formulaDsp { - -} - -img.formulaInl { - vertical-align: middle; -} - -/* @group Code Colorization */ - -span.keyword { - color: #008000 -} - -span.keywordtype { - color: #604020 -} - -span.keywordflow { - color: #e08000 -} - -span.comment { - color: #800000 -} - -span.preprocessor { - color: #806020 -} - -span.stringliteral { - color: #002080 -} - -span.charliteral { - color: #008080 -} - -span.vhdldigit { - color: #ff00ff -} - -span.vhdlchar { - color: #000000 -} - -span.vhdlkeyword { - color: #700070 -} - -span.vhdllogic { - color: #ff0000 -} - -/* @end */ - -.search { - color: #003399; - font-weight: bold; -} - -form.search { - margin-bottom: 0px; - margin-top: 0px; -} - -input.search { - font-size: 75%; - color: #000080; - font-weight: normal; - background-color: #e8eef2; -} - -td.tiny { - font-size: 75%; -} - -.dirtab { - padding: 4px; - border-collapse: collapse; - border: 1px solid #84b0c7; -} - -th.dirtab { - background: #e8eef2; - font-weight: bold; -} - -hr { - height: 0; - border: none; - border-top: 1px solid #666; -} - -/* @group Member Descriptions */ - -.mdescLeft, .mdescRight, -.memItemLeft, .memItemRight, -.memTemplItemLeft, .memTemplItemRight, .memTemplParams { - background-color: #FAFAFA; - border: none; - margin: 4px; - padding: 1px 0 0 8px; -} - -.mdescLeft, .mdescRight { - padding: 0px 8px 4px 8px; - color: #555; -} - -.memItemLeft, .memItemRight, .memTemplParams { - border-top: 1px solid #ccc; -} - -.memTemplParams { - color: #606060; -} - -/* @end */ - -/* @group Member Details */ - -/* Styles for detailed member documentation */ - -.memtemplate { - font-size: 80%; - color: #606060; - font-weight: normal; - margin-left: 3px; -} - -.memnav { - background-color: #e8eef2; - border: 1px solid #84b0c7; - text-align: center; - margin: 2px; - margin-right: 15px; - padding: 2px; -} - -.memitem { - padding: 0; -} - -.memname { - white-space: nowrap; - font-weight: bold; -} - -.memproto, .memdoc { - border: 1px solid #84b0c7; -} - -.memproto { - padding: 0; - background-color: #d5e1e8; - font-weight: bold; - -webkit-border-top-left-radius: 8px; - -webkit-border-top-right-radius: 8px; - -moz-border-radius-topleft: 8px; - -moz-border-radius-topright: 8px; -} - -.memdoc { - padding: 2px 5px; - background-color: #eef3f5; - border-top-width: 0; - -webkit-border-bottom-left-radius: 8px; - -webkit-border-bottom-right-radius: 8px; - -moz-border-radius-bottomleft: 8px; - -moz-border-radius-bottomright: 8px; -} - -.paramkey { - text-align: right; -} - -.paramtype { - white-space: nowrap; -} - -.paramname { - color: #602020; - white-space: nowrap; -} -.paramname em { - font-style: normal; -} - -/* @end */ - -/* @group Directory (tree) */ - -/* for the tree view */ - -.ftvtree { - font-family: sans-serif; - margin: 0.5em; -} - -/* these are for tree view when used as main index */ - -.directory { - font-size: 9pt; - font-weight: bold; -} - -.directory h3 { - margin: 0px; - margin-top: 1em; - font-size: 11pt; -} - -/* -The following two styles can be used to replace the root node title -with an image of your choice. Simply uncomment the next two styles, -specify the name of your image and be sure to set 'height' to the -proper pixel height of your image. -*/ - -/* -.directory h3.swap { - height: 61px; - background-repeat: no-repeat; - background-image: url("yourimage.gif"); -} -.directory h3.swap span { - display: none; -} -*/ - -.directory > h3 { - margin-top: 0; -} - -.directory p { - margin: 0px; - white-space: nowrap; -} - -.directory div { - display: none; - margin: 0px; -} - -.directory img { - vertical-align: -30%; -} - -/* these are for tree view when not used as main index */ - -.directory-alt { - font-size: 100%; - font-weight: bold; -} - -.directory-alt h3 { - margin: 0px; - margin-top: 1em; - font-size: 11pt; -} - -.directory-alt > h3 { - margin-top: 0; -} - -.directory-alt p { - margin: 0px; - white-space: nowrap; -} - -.directory-alt div { - display: none; - margin: 0px; -} - -.directory-alt img { - vertical-align: -30%; -} - -/* @end */ - -address { - font-style: normal; - color: #333; -} - -code { - text-decoration: none; - font-size: 110% -} - diff --git a/branch-3.0-2011/documentation/src/index.dox b/branch-3.0-2011/documentation/src/index.dox deleted file mode 100644 index 97ed150be..000000000 --- a/branch-3.0-2011/documentation/src/index.dox +++ /dev/null @@ -1,118 +0,0 @@ -/** - -\mainpage FLTK Programming Manual -<TABLE BGCOLOR="#9f9f9f" CELLPADDING="8" CELLSPACING="0" SUMMARY="TITLE BAR" WIDTH="100%" BORDER="0"> -<TR> - <TD><CENTER> - \image html FL200.png - \image latex FL200.png "" width=5cm - </CENTER></TD> - <TD><CENTER> - <B>FLTK 1.3.0 Programming Manual</B> - - Revision 9 by F. Costantini, D. Gibson, M. Melcher, - A. Schlosser, B. Spitzak and M. Sweet. - - Copyright 1998-2010 by Bill Spitzak and others. - </CENTER></TD> -</TR> -</TABLE> -<TABLE BGCOLOR="#9f9f9f" CELLPADDING="8" CELLSPACING="0" SUMMARY="TITLE BAR" WIDTH="100%" BORDER="0"> -<TR> - <TD> - This software and manual are provided under the terms of the GNU - Library General Public License. Permission is granted to reproduce - this manual or any portion for any purpose, provided this copyright - and permission notice are preserved. - </TD> -</TR> -</TABLE> -<TABLE BGCOLOR="#9f9fef" CELLPADDING="8" CELLSPACING="0" SUMMARY="Table of Contents" WIDTH="100%" BORDER="0"> -<TR> - <TD ALIGN="LEFT" VALIGN="TOP"> - - \subpage preface - - \subpage intro - - \subpage basics - - \subpage common - - \ref common_colors - - \ref common_boxtypes - - \ref common_labels - - \ref drawing_images - - \subpage editor - - \subpage drawing - - \subpage events - - \ref events_event_xxx - - \ref events_propagation - - \subpage subclassing - - \subpage opengl - - \subpage fluid - - \ref fluid_widget_attributes - - \ref fluid_selecting_moving - - \ref fluid_images - - </TD> - <TD ALIGN="LEFT" VALIGN="TOP"> - - \subpage advanced - - \subpage unicode - - - - <b>Appendices:</b> - - - \subpage enumerations - - - \subpage glut - - \ref glut_Fl_Glut_Window - <!-- - Fl_Glut_Window (not yet commented ?) --> - - - \subpage forms - - - \subpage osissues - - - \subpage migration_1_1 - - - \subpage migration_1_3 - - - \subpage development - - - \subpage license - - - \subpage examples - - </TD> -</TR> -</TABLE> - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="preface.html"> - Preface - [Next]</a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/input_choice.jpg b/branch-3.0-2011/documentation/src/input_choice.jpg Binary files differdeleted file mode 100644 index 7f7b93f85..000000000 --- a/branch-3.0-2011/documentation/src/input_choice.jpg +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/intro.dox b/branch-3.0-2011/documentation/src/intro.dox deleted file mode 100644 index 26abb298c..000000000 --- a/branch-3.0-2011/documentation/src/intro.dox +++ /dev/null @@ -1,348 +0,0 @@ -/** - - \page intro Introduction to FLTK - -The Fast Light Tool Kit ("FLTK", pronounced -"fulltick") is a cross-platform C++ GUI toolkit for -UNIX®/Linux® (X11), Microsoft® Windows®, and -Apple® OS X®. FLTK provides modern GUI functionality without the -bloat and supports 3D graphics via OpenGL® and its built-in -GLUT emulation. 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. - -\section intro_history 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 FLTK) are -\e 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 \e 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 -\e 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 whether it 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 than 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 -mechanism. - -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. - -\section intro_features Features - -FLTK was designed to be statically linked. This was done by -splitting it into many small objects and designing 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 -is now included with several Linux distributions. - -Here are some of the core features unique to FLTK: - -\li sizeof(Fl_Widget) == 64 to 92. - -\li The "core" (the "hello" program compiled & linked with a static FLTK - library using gcc on a 486 and then stripped) is 114K. - -\li The FLUID program (which includes every widget) is 538k. - -\li Written directly atop core libraries (Xlib, WIN32 or Cocoa) for - maximum speed, and carefully optimized for code size and performance. - -\li Precise low-level compatibility between the X11, WIN32 and MacOS - versions - only about 10% of the code is different. - -\li Interactive user interface builder program. Output is human-readable - and editable C++ source code. - -\li Support for overlay hardware, with emulation if none is available. - -\li Very small & fast portable 2-D drawing library to hide Xlib, WIN32, - or QuickDraw. - -\li OpenGL/Mesa drawing area widget. - -\li Support for OpenGL overlay hardware on both X11 and WIN32, with - emulation if none is available. - -\li Text widgets with cut & paste, undo, and support - for Unicode text and international input methods. - -\li Compatibility header file for the GLUT library. - -\li Compatibility header file for the XForms library. - -\section intro_licensing Licensing - -FLTK comes with complete free source code. -FLTK is available under the terms of the -\ref license "GNU Library General Public License" -with exceptions that allow for static linking. -Contrary to popular belief, it can be used in -commercial software - even Bill Gates could use it! - -\section intro_what What Does "FLTK" Mean? - -FLTK was originally designed to be compatible 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", including a bogus excuse that it -stands for "The Fast Light Toolkit". - -\section intro_unix Building and Installing FLTK Under UNIX and Apple OS X - -In most cases you can just type "make". This will -run configure with the default of no options and then compile -everything. - -For OS X, Xcode 3 project files can be found in the 'ide' directory. - -FLTK uses GNU autoconf to configure itself for your UNIX -platform. The main things that the configure script will look -for are the X11 and OpenGL (or Mesa) header and library files. -If these cannot be found in the standard include/library -locations you'll need to define the \p CFLAGS, -\p CXXFLAGS, and \p LDFLAGS environment variables. -For the Bourne and Korn shells you'd use: - -\code -CFLAGS=-Iincludedir; export CFLAGS -CXXFLAGS=-Iincludedir; export CXXFLAGS -LDFLAGS=-Llibdir; export LDFLAGS -\endcode - -For C shell and tcsh, use: - -\code -setenv CFLAGS "-Iincludedir" -setenv CXXFLAGS "-Iincludedir" -setenv LDFLAGS "-Llibdir" -\endcode - -By default configure will look for a C++ compiler named -\p CC, \p c++, \p g++, or \p gcc in that -order. To use another compiler you need to set the \p CXX -environment variable: - -\code -CXX=xlC; export CXX -setenv CXX "xlC" -\endcode - -The \p CC environment variable can also be used to -override the default C compiler (\p cc or \p gcc), -which is used for a few FLTK source files. - -You can run configure yourself to get the exact setup you need. -Type "./configure <options>", where options are: - -\par --enable-cygwin -Enable the Cygwin libraries under WIN32 - -\par --enable-debug -Enable debugging code & symbols - -\par --disable-gl -Disable OpenGL support - -\par --enable-shared -Enable generation of shared libraries - -\par --enable-threads -Enable multithreading support - -\par --enable-xdbe -Enable the X double-buffer extension - -\par --enable-xft -Enable the Xft library for anti-aliased fonts under X11 - -\par --enable-x11 -When targeting cygwin, build with X11 GUI instead of windows GDI - -\par --enable-cp936 -Under X11, enable use of the GB2312 locale - -\par --bindir=/path -Set the location for executables [default = $prefix/bin] - -\par --datadir=/path -Set the location for data files. [default = $prefix/share] - -\par --libdir=/path -Set the location for libraries [default = $prefix/lib] - -\par --includedir=/path -Set the location for include files. [default = $prefix/include] - -\par --mandir=/path -Set the location for man pages. [default = $prefix/man] - -\par --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". - -\section intro_windows Building FLTK Under Microsoft Windows - -There are three ways to build FLTK under Microsoft Windows. -The first is to use one of the VisualC project files in the -"ide" directory. Just open (or double-click on) -the "fltk.dsw" or "fltk.sln" file to get the whole shebang. - -The second method is to use the \p configure script -included with the FLTK software; this has only been tested with -the Cygwin tools: - -\code -sh configure --prefix=C:/FLTK -make -\endcode - -The final 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: - -\code -copy makefiles\Makefile.<env> Makefile -make -\endcode - -\subsection intro_visualcpp Using the Visual C++ DLL Library - -The "fltkdll.dsp" project file builds a DLL-version -of the FLTK library. Because of name mangling differences -between PC compilers (even between different versions of Visual -C++!) you can only use the DLL that is generated with the same -version compiler that you built it with. - -When compiling an application or DLL that uses the FLTK DLL, -you will need to define the \p FL_DLL preprocessor symbol -to get the correct linkage commands embedded within the FLTK -header files. - -\section intro_internet Internet Resources - -FLTK is available on the 'net in a bunch of locations: - -\par WWW -http://www.fltk.org/ <br> -http://www.fltk.org/str.php [for reporting bugs] <br> -http://www.fltk.org/software.php [source code]<br> -http://www.fltk.org/newsgroups.php [newsgroup/forums] - -\par FTP -http://ftp.easysw.com/pub/fltk [California, USA, via http]<br> -ftp://ftp.easysw.com/pub/fltk [California, USA via ftp]<br> -ftp://ftp2.easysw.com/pub/fltk [Maryland, USA]<br> -ftp://ftp.funet.fi/pub/mirrors/ftp.easysw.com/pub/fltk [Espoo, Finland]<br> - -\par NNTP Newsgroups -news://news.easysw.com/ [NNTP interface]<br> -http://fltk.org/newsgroups.php [web interface]<br> - -Point your NNTP news reader at news.easysw.com. At minimum, you'll want to subscribe -to the "fltk.general" group for general FLTK questions and answers. - -You can also use the web interface to the newsgroup; just go to the main http://fltk.org/ -page and click on "Forums". - -\section intro_reporting Reporting Bugs - -To report a bug in FLTK, or for feature requests, please use the form at -<A href="http://www.fltk.org/str.php">http://www.fltk.org/str.php</A>, -and click on "Submit Bug or Feature Request". - -You'll be prompted for the FLTK version, operating system & version, -and compiler that you are using. We will be unable to provide -any kind of help without that basic information. - -For general support and questions, please use the fltk.general newsgroup (see above, "NNTP Newsgroups") -or the web interface to the newsgroups at <A href="http://fltk.org/newsgroups.php">http://fltk.org/newsgroups.php</A>. - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="preface.html"> - [Prev] - Preface - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="basics.html"> - FLTK Basics - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/license.dox b/branch-3.0-2011/documentation/src/license.dox deleted file mode 100644 index 124b9ba17..000000000 --- a/branch-3.0-2011/documentation/src/license.dox +++ /dev/null @@ -1,518 +0,0 @@ -/** - - \page license Software License - -\par December 11, 2001 - -The FLTK library and included programs are provided under the terms -of the GNU Library General Public License (LGPL) with the following -exceptions: - --# 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.<BR> - <BR> - The authors do request that such modifications be - contributed to the FLTK project - send all contributions - through the "Software Trouble Report" on the following page: - http://www.fltk.org/str.php<BR> - <BR> --# Widgets that are subclassed from FLTK widgets do not - constitute a derivative work.<BR> - <BR> --# 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.<BR> - <BR> - 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.<BR> - <BR> --# 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.<BR> - <BR> - However, programs must still identify their use of FLTK. - The following example statement can be included in user - documentation to satisfy this requirement:<BR> - <BR> - <I>[program/widget] is based in part on the work of - the FLTK project (http://www.fltk.org).</I> - -<HR> - -\par GNU LIBRARY GENERAL PUBLIC LICENSE - -Version 2, June 1991 <BR> -Copyright (C) 1991 Free Software Foundation, Inc. <BR> -59 Temple Place - Suite 330, Boston, MA 02111-1307, USA <BR> -Everyone is permitted to copy and distribute verbatim copies of -this license document, but changing it is not allowed. <BR> -[This is the first released version of the library GPL. It is -numbered 2 because it goes with version 2 of the ordinary GPL.] - -\par 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. - -\par TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - -\b 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. - -\b 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. - -\b 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: - -\b a) The modified work must itself be a software library. - -\b b) You must cause the files modified to carry -prominent notices stating that you changed the files and the date of -any change. - -\b 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. - -\b 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. - -\b 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. - -\b 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. - -\b 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. - -\b 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: - -\b 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 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. - -\b 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. - -\b 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. - -\b 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: - -\b 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 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. - - -\b 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. - -\b 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. - -\b 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. - -\b 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. - -\b 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. - -\b 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. - -\b 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. - -\par NO WARRANTY - -\b 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. - -\b 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. - -\par END OF TERMS AND CONDITIONS - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="development.html"> - [Prev] - Developer Information - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="examples.html"> - Example Source Code - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/menu.png b/branch-3.0-2011/documentation/src/menu.png Binary files differdeleted file mode 100644 index eafeb957f..000000000 --- a/branch-3.0-2011/documentation/src/menu.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/menu_button.png b/branch-3.0-2011/documentation/src/menu_button.png Binary files differdeleted file mode 100644 index 704c0e623..000000000 --- a/branch-3.0-2011/documentation/src/menu_button.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/menubar.png b/branch-3.0-2011/documentation/src/menubar.png Binary files differdeleted file mode 100644 index a2943769e..000000000 --- a/branch-3.0-2011/documentation/src/menubar.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/migration_1_1.dox b/branch-3.0-2011/documentation/src/migration_1_1.dox deleted file mode 100644 index dcb767103..000000000 --- a/branch-3.0-2011/documentation/src/migration_1_1.dox +++ /dev/null @@ -1,176 +0,0 @@ -/** - - \page migration_1_1 Migrating Code from FLTK 1.0 to 1.1 - - -This appendix describes the differences between the FLTK -1.0.x and FLTK 1.1.x functions and classes. - -\section migration_1_1_color Color Values - -Color values are now stored in a 32-bit unsigned integer -instead of the unsigned character in 1.0.x. This allows for the -specification of 24-bit RGB values or 8-bit FLTK color indices. - -\c FL_BLACK and \c FL_WHITE now remain black and white, even if -the base color of the gray ramp is changed using Fl::background(). -\c FL_DARK3 and \c FL_LIGHT3 can be used instead to -draw a very dark or a very bright background hue. - -Widgets use the new color symbols \c FL_FORGROUND_COLOR, -\c FL_BACKGROUND_COLOR, \c FL_BACKGROUND2_COLOR, -\c FL_INACTIVE_COLOR, and \c FL_SELECTION_COLOR. -More details can be found in the chapter \ref enumerations. - -\section migration_1_1_cutnpaste Cut and Paste Support - -The FLTK clipboard is now broken into two parts - a local -selection value and a cut-and-paste value. This allows FLTK to -support things like highlighting and replacing text that was -previously cut or copied, which makes FLTK applications behave -like traditional GUI applications. - -\section migration_1_1_file_chooser File Chooser - -The file chooser in FLTK 1.1.x is significantly different -than the one supplied with FLTK 1.0.x. Any code that directly -references the old \c FCB class or members will need -to be ported to the new Fl_File_Chooser class. - -\section migration_1_1_functions Function Names - -Some function names have changed from FLTK 1.0.x to 1.1.x in -order to avoid name space collisions. You can still use the old -function names by defining the \c FLTK_1_0_COMPAT symbol on -the command-line when you compile (\c -DFLTK_1_0_COMPAT) or in -your source, e.g.: - -\code -#define FLTK_1_0_COMPAT -#include <FL/Fl.H> -#include <FL/Enumerations.H> -#include <FL/filename.H> -\endcode - -The following table shows the old and new function names: - -<CENTER> -<TABLE WIDTH="80%" BORDER="1"> -<TR> - <TH>Old 1.0.x Name</TH> - <TH>New 1.1.x Name</TH> -</TR> -<TR> - <TD>contrast()</TD> - <TD>fl_contrast()</TD> -</TR> -<TR> - <TD>down()</TD> - <TD>fl_down()</TD> -</TR> -<TR> - <TD>filename_absolute()</TD> - <TD>fl_filename_absolute()</TD> -</TR> -<TR> - <TD>filename_expand()</TD> - <TD>fl_filename_expand()</TD> -</TR> -<TR> - <TD>filename_ext()</TD> - <TD>fl_filename_ext()</TD> -</TR> -<TR> - <TD>filename_isdir()</TD> - <TD>fl_filename_isdir()</TD> -</TR> -<TR> - <TD>filename_list()</TD> - <TD>fl_filename_list()</TD> -</TR> -<TR> - <TD>filename_match()</TD> - <TD>fl_filename_match()</TD> -</TR> -<TR> - <TD>filename_name()</TD> - <TD>fl_filename_name()</TD> -</TR> -<TR> - <TD>filename_relative()</TD> - <TD>fl_filename_relative()</TD> -</TR> -<TR> - <TD>filename_setext()</TD> - <TD>fl_filename_setext()</TD> -</TR> -<TR> - <TD>frame()</TD> - <TD>fl_frame()</TD> -</TR> -<TR> - <TD>inactive()</TD> - <TD>fl_inactive()</TD> -</TR> -<TR> - <TD>numericsort()</TD> - <TD>fl_numericsort()</TD> -</TR> -</TABLE> -</CENTER> - -\section migration_1_1_images Image Support - -Image support in FLTK has been significantly revamped in 1.1.x. -The Fl_Image class is now a proper base class, with the core -image drawing functionality in the Fl_Bitmap, Fl_Pixmap, and -Fl_RGB_Image classes. - -BMP, GIF, JPEG, PNG, XBM, and XPM image files can now be -loaded using the appropriate image classes, and the -Fl_Shared_Image class can be used to cache images in memory. - -Image labels are no longer provided as an add-on label type. -If you use the old \c label() methods on an image, the -widget's \c image() method is called to set the image -as the label. - -Image labels in menu items must still use the old labeltype -mechanism to preserve source compatibility. - -\section migration_1_1_keyboard Keyboard Navigation - -FLTK 1.1.x now supports keyboard navigation and control with -all widgets. To restore the old FLTK 1.0.x behavior so that only -text widgets get keyboard focus, call the Fl::visible_focus() -method to disable it: - -\code -Fl::visible_focus(0); -\endcode - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="osissues.html"> - [Prev] - Operating System Issues - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="migration_1_3.html"> - Migrating Code from FLTK 1.1 to 1.3 - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/migration_1_3.dox b/branch-3.0-2011/documentation/src/migration_1_3.dox deleted file mode 100644 index 4c1f1bfba..000000000 --- a/branch-3.0-2011/documentation/src/migration_1_3.dox +++ /dev/null @@ -1,80 +0,0 @@ -/** - - \page migration_1_3 Migrating Code from FLTK 1.1 to 1.3 - -This appendix describes the differences between the FLTK -1.1.x and FLTK 1.3.x functions and classes. - -\section migration_1_3_fltk_1_0 Migrating From FLTK 1.0 - -If you want to migrate your code from FLTK 1.0 to FLTK 1.3, -then you should first consult Appendix \ref migration_1_1. - - -\section migration_1_3_fl_scroll Fl_Scroll Widget - -Fl_Scroll::scroll_to(int x, int y) replaces Fl_Scroll::position(int x, int y). - -This change was needed because Fl_Scroll::position(int,int) redefined -Fl_Widget::position(int,int), but with a completely different function (moving -the scrollbars instead of moving the widget). - -Please be aware that you need to change your application's code for all -Fl_Scroll-derived widgets, if you used Fl_Scroll::position(int x, int y) -to position <b>the scrollbars</b> (not the widget itself). - -The compiler will not detect any errors, because your calls to -\b position(int x, int y) will be calling Fl_Widget::position(int x, int y). - - -\section migration_1_3_unicode Unicode (UTF-8) - -FLTK 1.3 uses Unicode (UTF-8) encoding internally. If you are only using -characters in the ASCII range (32-127), there is a high probability that -you don't need to modify your code. However, if you use international -characters (128-255), encoded as e.g. Windows codepage 1252, ISO-8859-1, -ISO-8859-15 or any other encoding, then you will need to update your character -string constants and widget input data accordingly. - -Please refer to the \ref unicode chapter for more details. - -\note It is important that, although your software uses only ASCII characters -for input to FLTK widgets, the user may enter non-ASCII characters, and FLTK -will return these characters with utf-8 encoding to your application, e.g. -via Fl_Input::value(). You \b will need to re-encode them to \b your (non-utf-8) -encoding, otherwise you might see or print garbage in your data. - - -\section migration_1_3_int_coords Widget Coordinate Representation - -FLTK 1.3 changed all Widget coordinate variables and methods, e.g. -Fl_Widget::x(), Fl_Widget::y(), Fl_Widget::w(), Fl_Widget::h(), from -short (16-bit) to int (32-bit) representation. This should not affect -any existing code, but makes it possible to use bigger scroll areas -(e.g. Fl_Scroll widget). - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="migration_1_1.html"> - [Prev] - Migrating Code from FLTK 1.0 to 1.1 - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="development.html"> - Developer Information - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/opengl.dox b/branch-3.0-2011/documentation/src/opengl.dox deleted file mode 100644 index 51882a293..000000000 --- a/branch-3.0-2011/documentation/src/opengl.dox +++ /dev/null @@ -1,473 +0,0 @@ -/** - - \page opengl Using OpenGL - -This chapter discusses using FLTK for your OpenGL applications. - -\section opengl_using Using OpenGL in FLTK - -The easiest way to make an OpenGL display is to subclass -Fl_Gl_Window. -Your subclass must implement a \p draw() method which uses -OpenGL calls to draw the display. Your main program should call -\p redraw() when the display needs to change, and -(somewhat later) FLTK will call \p 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 -\ref opengl_gl_start "gl_start()" and -\ref opengl_gl_finish "gl_finish()" -functions around your OpenGL code. - -You must include FLTK's \p <FL/gl.h> header -file. It will include the file \p <GL/gl.h>, define -some extra drawing functions provided by FLTK, and include the -\p <windows.h> header file needed by WIN32 -applications. - -\section opengl_subclass Making a Subclass of Fl_Gl_Window - -To make a subclass of Fl_Gl_Window, you must provide: - -\li A class definition. -\li A \p draw() method. -\li A \p handle() method if you need to receive input from the user. - -If your subclass provides static controls in the window, they -must be redrawn whenever the \p FL_DAMAGE_ALL bit is set -in the value returned by \p 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: - -\code -#ifndef MESA -glDrawBuffer(GL_FRONT_AND_BACK); -#endif // !MESA -... draw stuff here ... -#ifndef MESA -glDrawBuffer(GL_BACK); -#endif // !MESA -\endcode - -<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> -<TR> - <TD><B>Note:</B> - - If you are using the Mesa graphics library, the call - to \p 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. - - </TD> - -</TR> -</TABLE></CENTER> - -\subsection opengl_defining Defining the Subclass - -To define the subclass you just subclass the Fl_Gl_Window class: - -\code -class MyWindow : public Fl_Gl_Window { - void draw(); - int handle(int); - -public: - MyWindow(int X, int Y, int W, int H, const char *L) - : Fl_Gl_Window(X, Y, W, H, L) {} -}; -\endcode - -The \p draw() and \p 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.) - -\subsection opengl_draw The draw() Method - -The \p draw() method is where you actually do your OpenGL drawing: - -\code -void MyWindow::draw() { - if (!valid()) { - ... set up projection, viewport, etc ... - ... window size is in w() and h(). - ... valid() is turned on by FLTK after draw() returns - } - ... draw ... -} -\endcode - -\subsection opengl_handle The handle() Method - -The \p handle() method handles mouse and keyboard -events for the window: - -\code -int MyWindow::handle(int event) { - switch(event) { - case FL_PUSH: - ... mouse down event ... - ... position in Fl::event_x() and Fl::event_y() - return 1; - case FL_DRAG: - ... mouse moved while down event ... - return 1; - case FL_RELEASE: - ... mouse up event ... - return 1; - case FL_FOCUS : - case FL_UNFOCUS : - ... Return 1 if you want keyboard events, 0 otherwise - return 1; - case FL_KEYBOARD: - ... keypress, key is in Fl::event_key(), ascii in Fl::event_text() - ... Return 1 if you understand/use the keyboard event, 0 otherwise... - return 1; - case FL_SHORTCUT: - ... shortcut, key is in Fl::event_key(), ascii in Fl::event_text() - ... Return 1 if you understand/use the shortcut event, 0 otherwise... - return 1; - default: - // pass other events to the base class... - return Fl_Gl_Window::handle(event); - } -} -\endcode - -When \p handle() is called, the OpenGL context is not -set up! If your display changes, you should call -\p redraw() and let \p draw() do the work. Don't -call any OpenGL drawing functions from inside \p handle()! - -You can call \e some OpenGL stuff like hit detection and texture -loading functions by doing: - -\code - case FL_PUSH: - make_current(); // make OpenGL context current - if (!valid()) { - - ... set up projection exactly the same as draw ... - - valid(1); // stop it from doing this next time - } - ... ok to call NON-DRAWING OpenGL code here, such as hit - detection, loading textures, etc... -\endcode - -Your main program can now create one of your windows by doing -<tt>new MyWindow(...)</tt>. - -You can also use your new window class in -\ref fluid "FLUID" -by: - --# Putting your class definition in a \p MyWindow.H file. --# Creating a Fl_Box widget in FLUID. --# In the widget panel fill in the "class" field with \p MyWindow. - This will make FLUID produce constructors for your new class. --# In the "Extra Code" field put <tt>\#include "MyWindow.H"</tt>, - so that the FLUID output file will compile. - -You must put <tt>glwindow->show()</tt> in your main code -after calling \p show() on the window containing the -OpenGL window. - -\section opengl_normal Using OpenGL in Normal FLTK Windows - -You can put OpenGL code into the \p draw() method, as described in -\ref subclassing_drawing -in the previous chapter, or into the code for a -\ref common_boxtypes "boxtype" -or other places with some care. - -Most importantly, before you show \e any windows, -including those that don't have OpenGL drawing, you <B>must</B> -initialize FLTK so that it knows it is going to use OpenGL. You -may use any of the symbols described for \p Fl_Gl_Window::mode() -to describe how you intend to use OpenGL: - -\code -Fl::gl_visual(FL_RGB); -\endcode - -\anchor opengl_gl_start -\anchor opengl_gl_finish -You can then put OpenGL drawing code anywhere you can draw -normally by surrounding it with -gl_start() and gl_finish() to set up, and later release, 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 \p glScissor() -commands. These functions also synchronize the OpenGL graphics stream -with the drawing done by other X, WIN32, or FLTK functions. - -\code -gl_start(); -... put your OpenGL code here ... -gl_finish(); -\endcode - -The same context is reused each time. If your code changes -the projection transformation or anything else you should use -\p glPushMatrix() and \p glPopMatrix() functions to -put the state back before calling \p gl_finish(). - -You may want to use <tt>Fl_Window::current()-\>h()</tt> 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: - -\li You must choose a default visual with Fl::gl_visual(). - -\li You cannot pass \p FL_DOUBLE to Fl::gl_visual(). - -\li You cannot use Fl_Double_Window or Fl_Overlay_Window. - -Do \e not call \p gl_start() or -\p gl_finish() when drawing into an Fl_Gl_Window ! - -\section opengl_drawing OpenGL Drawing Functions - -FLTK provides some useful OpenGL drawing functions. They can -be freely mixed with any OpenGL calls, and are defined by -including \p <FL/gl.h> which you should include -instead of the OpenGL header \p <GL/gl.h>. - -void gl_color(Fl_Color) - -\par -Sets the current OpenGL color to a FLTK color. <I>For -color-index modes it will use \p fl_xpixel(c), which is -only right if this window uses the default colormap!</I> - -void gl_rect(int x, int y, int w, int h) <br> -void gl_rectf(int x, int y, int w, int h) - -\par -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) - -\par -Sets the current OpenGL font to the same font you get by calling -\ref ssect_Fonts "fl_font()". - -int gl_height() <br> -int gl_descent() <br> -float gl_width(const char *s) <br> -float gl_width(const char *s, int n) <br> -float gl_width(uchar c) - -\par -Returns information about the current OpenGL font. - -void gl_draw(const char *s) <br> -void gl_draw(const char *s, int n) - -\par -Draws a nul-terminated string or an array of \p n -characters in the current OpenGL font at the current raster -position. - -void gl_draw(const char *s, int x, int y) <br> -void gl_draw(const char *s, int n, int x, int y) <br> -void gl_draw(const char *s, float x, float y) <br> -void gl_draw(const char *s, int n, float x, float y) - -\par -Draws a nul-terminated string or an array of \p n -characters in the current OpenGL font at the given position. - -void gl_draw(const char *s, int x, int y, int w, int h, Fl_Align) - -\par -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 -\ref ssect_Text "fl_draw()". - -\section opengl_speed Speeding up OpenGL - -Performance of Fl_Gl_Window may be improved on some types of -OpenGL implementations, in particular MESA and other software -emulators, by setting the \p GL_SWAP_TYPE environment -variable. This variable declares what is in the backbuffer after -you do a swapbuffers. - -\li <tt>setenv GL_SWAP_TYPE COPY</tt> <br> - <br> - This indicates that the back buffer is copied to the - front buffer, and still contains its old data. This is - true of many hardware implementations. Setting this - will speed up emulation of overlays, and widgets that - can do partial update can take advantage of this as - \p damage() will not be cleared to -1. - -\li <tt>setenv GL_SWAP_TYPE NODAMAGE</tt> <br> - <br> - This indicates that nothing changes the back buffer - except drawing into it. This is true of MESA and Win32 - software emulation and perhaps some hardware emulation - on systems with lots of memory. - -\li All other values for \p GL_SWAP_TYPE, and not - setting the variable, cause FLTK to assume that the - back buffer must be completely redrawn after a swap. - -This is easily tested by running the \ref examples_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. - -\section opengl_optimizer Using OpenGL Optimizer with FLTK - -<A href="http://www.sgi.com/software/optimizer">OpenGL Optimizer</A> -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. - -\par OptimizerWindow Class Definition - -\par -To use -<A href="http://www.sgi.com/software/optimizer">OpenGL Optimizer</A> -with FLTK you'll need to create a -subclass of Fl_Gl_Widget that includes several state -variables: - -\code -class OptimizerWindow : public Fl_Gl_Window { - csContext *context_; // Initialized to 0 and set by draw()... - csDrawAction *draw_action_; // Draw action... - csGroup *scene_; // Scene to draw... - csCamara *camera_; // Viewport for scene... - - void draw(); - -public: - OptimizerWindow(int X, int Y, int W, int H, const char *L) - : Fl_Gl_Window(X, Y, W, H, L) { - context_ = (csContext *)0; - draw_action_ = (csDrawAction *)0; - scene_ = (csGroup *)0; - camera_ = (csCamera *)0; - } - - void scene(csGroup *g) { scene_ = g; redraw(); } - - void camera(csCamera *c) { - camera_ = c; - if (context_) { - draw_action_->setCamera(camera_); - camera_->draw(draw_action_); - redraw(); - } - } -}; -\endcode - -\par The camera() Method - -\par -The \p camera() method sets the camera (projection and -viewpoint) to use when drawing the scene. The scene is redrawn after -this call. - -\par The draw() Method - -\par -The \p draw() method performs the needed initialization and does -the actual drawing: - -\code -void OptimizerWindow::draw() { - if (!context_) { - // This is the first time we've been asked to draw; create the - // Optimizer context for the scene... - -#ifdef WIN32 - context_ = new csContext((HDC)fl_getHDC()); - context_->ref(); - context_->makeCurrent((HDC)fl_getHDC()); -#else - context_ = new csContext(fl_display, fl_visual); - context_->ref(); - context_->makeCurrent(fl_display, fl_window); -#endif // WIN32 - - ... perform other context setup as desired ... - - // Then create the draw action to handle drawing things... - - draw_action_ = new csDrawAction; - if (camera_) { - draw_action_->setCamera(camera_); - camera_->draw(draw_action_); - } - } else { -#ifdef WIN32 - context_->makeCurrent((HDC)fl_getHDC()); -#else - context_->makeCurrent(fl_display, fl_window); -#endif // WIN32 - } - - if (!valid()) { - // Update the viewport for this context... - context_->setViewport(0, 0, w(), h()); - } - - // Clear the window... - context_->clear(csContext::COLOR_CLEAR | csContext::DEPTH_CLEAR, - 0.0f, // Red - 0.0f, // Green - 0.0f, // Blue - 1.0f); // Alpha - - // Then draw the scene (if any)... - if (scene_) - draw_action_->apply(scene_); -} -\endcode - -\par The scene() Method - -\par -The \p scene() method sets the scene to be drawn. The scene is -a collection of 3D objects in a \p csGroup. The scene is redrawn -after this call. - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="subclassing.html"> - [Prev] - Adding and Extending Widgets - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="fluid.html"> - Programming with FLUID - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/osissues.dox b/branch-3.0-2011/documentation/src/osissues.dox deleted file mode 100644 index 38a776143..000000000 --- a/branch-3.0-2011/documentation/src/osissues.dox +++ /dev/null @@ -1,792 +0,0 @@ -/** - - \page osissues Operating System Issues - -This appendix describes the operating system specific interfaces in FLTK. - -\section osissues_accessing Accessing the OS Interfaces - -All programs that need to access the operating system -specific interfaces must include the following header file: - -\code -#include <FL/x.H> -\endcode - -Despite the name, this header file will define the -appropriate interface for your environment. The pages that -follow describe the functionality that is provided for each -operating system. - -<CENTER> -<TABLE WIDTH="90%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> -<TR> - <TD><B>WARNING:</B> - - The interfaces provided by this header file may - change radically in new FLTK releases. Use them only - when an existing generic FLTK interface is not - sufficient. - - </TD> -</TR> -</TABLE> -</CENTER> - -\section osissues_unit The UNIX (X11) Interface - -The UNIX interface provides access to the X Window System -state information and data structures. - -\subsection osissues_x_events Handling Other X Events - -void Fl::add_handler(int (*f)(int)) - -\par -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. - -\par -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 in the \c fl_xevent variable. - -\par -The argument is the FLTK event type that was not handled, or -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, for example -\c FL_SHORTCUT. - -extern XEvent *fl_xevent - -\par -This variable contains the most recent X event. - -extern ulong fl_event_time - -\par -This variable contains the time stamp from the most recent X -event that reported it; not all events do. Many X calls like cut -and paste need this value. - -Window fl_xid(const Fl_Window *) - -\par -Returns the XID for a window, or zero if not \c shown(). - -Fl_Window *fl_find(ulong xid) - -\par -Returns the Fl_Window that corresponds to the given -XID, or \c NULL if not found. This function uses a cache -so it is slightly faster than iterating through the windows -yourself. - -int fl_handle(const XEvent &) - -\par -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 non-zero if FLTK understood the event. If the -window does not belong to FLTK and the \c add_handler() -functions all return 0, this function will return false. - -\par -Besides feeding events your code should call Fl::flush() -periodically so that FLTK redraws its windows. - -\par -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. - -\subsection osissues_drawing_xlib Drawing using Xlib - -The following global variables are set before -Fl_Widget::draw() is called, or by Fl_Window::make_current(): - -\code -extern Display *fl_display; -extern Window fl_window; -extern GC fl_gc; -extern int fl_screen; -extern XVisualInfo *fl_visual; -extern Colormap fl_colormap; -\endcode - -You must use them to produce Xlib calls. Don't attempt to change -them. A typical X drawing call is written like this: - -\code -XDrawSomething(fl_display, fl_window, fl_gc, ...); -\endcode - -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) <br> -unsigned long fl_xpixel(uchar r, uchar g, uchar b) - -\par -Returns the X pixel number used to draw the given FLTK color -index or RGB color. This is the X pixel that -\ref drawing_colors "fl_color()" -would use. - -int fl_parse_color(const char* p, uchar& r, uchar& g, uchar& b) - -\par -Convert a name into the red, green, and blue values of a color -by parsing the X11 color names. On other systems, \c fl_parse_color() -can only convert names in hexadecimal encoding, for example <tt>\#ff8083</tt>. - -extern XFontStruct *fl_xfont - -\par -Points to the font selected by the most recent -\ref ssect_Fonts "fl_font()". -This is not necessarily the current font of \c fl_gc, -which is not set until -\ref ssect_Text "fl_draw()" -is called. If FLTK was compiled with Xft support, \c fl_xfont -will usually be 0 and \c fl_xftfont will contain a pointer -to the \c XftFont structure instead. - -extern void *fl_xftfont - -\par -If FLTK was compiled with Xft support enabled, \c fl_xftfont -points to the xft font selected by the most recent -\ref ssect_Fonts "fl_font()". -Otherwise it will be 0. \c fl_xftfont should be cast to -<tt>XftFont*</tt>. - -\subsection osissues_xvisual 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 -<I> -before the first Fl_Window::show() is called. -</I> -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 *) - -\par -Set which X display to use. This actually does -<tt>putenv("DISPLAY=...")</tt> so that child programs -will display on the same screen if called with \c exec(). -This must be done before the display is opened. This call is -provided under MacOS and WIN32 but it has no effect. - -extern Display *fl_display - -\par -The open X display. This is needed as an argument to most -Xlib calls. Don't attempt to change it! This is \c NULL -before the display is opened. - -void fl_open_display() - -\par -Opens the display. Does nothing if it is already open. This -will make sure \c 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 \c show() of a window. - -\par -This may call Fl::abort() if there is an error opening the display. - -void fl_close_display() - -\par -This closes the X connection. You do \e 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 - -\par -Which screen number to use. This is set by -\c 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 <br> -extern Colormap fl_colormap - -\par -The visual and colormap that FLTK will use for all windows. -These are set by \c fl_open_display() to the default -visual and colormap. You can change them before calling -\c show() on the first window. Typical code for changing -the default visual is: -\code -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); -// it is now ok to show() windows: -window->show(argc, argv); -\endcode - -\subsection osissues_specialx 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 \c 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() - -\par -If the window is already \c shown() this must cause it -to be raised, this can usually be done by calling Fl_Window::show(). -If not \c shown() your implementation must call either -Fl_X::set_xid() or Fl_X::make_xid(). - -\par -An example: -\code -void MyWindow::show() { - if (shown()) {Fl_Window::show(); return;} // you must do this! - fl_open_display(); // necessary if this is first window - // we only calculate 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); - } - Fl_X::make_xid(this, visual, colormap); -} -\endcode - -\verbatim -Fl_X *Fl_X::set_xid(Fl_Window*, Window xid) -\endverbatim - -\par -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) - -\par -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() - -\par -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 \c fl_window and \c fl_gc -and then calling the \c draw() method. For -your own windows you might just want to put all the drawing code -in here. - -\par -The X region that is a combination of all \c damage() -calls done so far is in <tt>Fl_X::i(this)->region</tt>. If -\c NULL then you should redraw the entire window. The -undocumented function \c fl_clip_region(XRegion) will -initialize the FLTK clip stack with a region or \c NULL -for no clipping. You must set region to \c NULL afterwards -as \c fl_clip_region() will own and delete it when -done. - -\par -If <tt>damage() & FL_DAMAGE_EXPOSE</tt> then only X -expose events have happened. This may be useful if you have an -undamaged image (such as a backing buffer) around. - -\par -Here is a sample where an undamaged image is kept somewhere: -\code -void MyWindow::flush() { - 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 ... -} -\endcode - -virtual void Fl_Window::hide() - -\par -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 \c xid(). If you override -this, you must also override the destructor as shown: -\code -void MyWindow::hide() { - if (mypixmap) { - XFreePixmap(fl_display,mypixmap); - mypixmap = 0; - } - Fl_Window::hide(); // you must call this -} -\endcode - -virtual void Fl_Window::~Fl_Window() - -\par -Because of the way C++ works, if you override \c hide() -you \e must override the destructor as well (otherwise only -the base class \c hide() is called): -\code -MyWindow::~MyWindow() { - hide(); -} -\endcode - -\subsection osissues_x_icon Setting the Icon of a Window - -FLTK currently supports setting a window's icon \b before it -is shown using the Fl_Window::icon() method. - -void Fl_Window::icon(const void *) - -\par -Sets the icon for the window to the passed pointer. You will -need to cast the icon \c Pixmap to a \c char* when -calling this method. To set a monochrome icon using a bitmap compiled -with your application use: -\code -#include "icon.xbm" - -fl_open_display(); // needed if display has not been previously opened - -Pixmap p = XCreateBitmapFromData(fl_display, DefaultRootWindow(fl_display), - icon_bits, icon_width, icon_height); - -window->icon((const void*)p); -\endcode - -\par -To use a multi-colored icon, the XPM format and library -should be used as follows: -\code -#include <X11/xpm.h> -#include "icon.xpm" - -fl_open_display(); // needed if display has not been previously opened - -Pixmap p, mask; - -XpmCreatePixmapFromData(fl_display, DefaultRootWindow(fl_display), - icon_xpm, &p, &mask, NULL); - -window->icon((const void *)p); -\endcode - -\par -When using the Xpm library, be sure to include it in the list -of libraries that are used to link the application (usually "-lXpm"). - -<CENTER> -<TABLE WIDTH="90%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> -<TR> - <TD><B>NOTE:</B> - - You must call Fl_Window::show(int argc, char** argv) - for the icon to be used. The Fl_Window::show() method - does not bind the icon to the window. - - </TD> -</TR> -</TABLE> -</CENTER> - -\subsection osissues_xresources X Resources - -When the -Fl_Window::show(int argc, char** argv) -method is called, FLTK looks for the following X resources: - -\li \c background - The default background color - for widgets (color). - -\li \c dndTextOps - The default setting for - drag and drop text operations (boolean). - -\li \c foreground - The default foreground (label) - color for widgets (color). - -\li \c scheme - The default scheme to use (string). - -\li \c selectBackground - The default selection - color for menus, etc. (color). - -\li <tt>Text.background</tt> - The default background - color for text fields (color). - -\li \c tooltips - The default setting for - tooltips (boolean). - -\li \c visibleFocus - The default setting for - visible keyboard focus on non-text widgets (boolean). - -Resources associated with the first window's Fl_Window::xclass() -string are queried first, or if no class has been specified then -the class "fltk" is used (e.g. <tt>fltk.background</tt>). If no -match is found, a global search is done (e.g. -<tt>*background</tt>). - -\section osissues_win32 The Windows (WIN32) Interface - -The Windows interface provides access to the WIN32 GDI -state information and data structures. - -\subsection osissues_win32_messages Handling Other WIN32 Messages - -By default a single WNDCLASSEX called "FLTK" is -created. All Fl_Window 's 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(), as it will call \c DispatchMessage() -for all messages to the other windows. If necessary you can let -the other library take over as long as it calls -\c DispatchMessage(), but you will have to arrange for the -function Fl::flush() to be called regularly so that -widgets are updated, timeouts are handled, and the idle -functions are called. - -extern MSG fl_msg - -\par -This variable contains the most recent message read by -\c 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)) - -\par -Installs 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 -functions is the FLTK event that was not handled or zero for -unknown messages. If all the handlers return zero then FLTK -calls \c DefWindowProc(). - -HWND fl_xid(const Fl_Window *) - -\par -Returns the window handle for a Fl_Window, or zero -if not \c shown(). - -Fl_Window *fl_find(HWND xid) - -\par -Returns the Fl_Window that corresponds to the given -window handle, or \c NULL if not found. This function uses -a cache so it is slightly faster than iterating through the -windows yourself. - -\subsection osissues_win32_gdi Drawing Things Using the WIN32 GDI - -When the virtual function Fl_Widget::draw() is -called, FLTK stores all the extra arguments you need to -make a proper GDI call in some global variables: - -\code -extern HINSTANCE fl_display; -extern HWND fl_window; -extern HDC fl_gc; -COLORREF fl_RGB(); -HPEN fl_pen(); -HBRUSH fl_brush(); -\endcode - -These global variables are set before Fl_Widget::draw() is called, or by -Fl_Window::make_current(). -You can refer to them when needed to produce GDI calls, but don't -attempt to change them. The functions return GDI objects for -the current color set by -\ref drawing_colors "fl_color()" -and are created as -needed and cached. A typical GDI drawing call is written like -this: - -\code -DrawSomething(fl_gc, ..., fl_brush()); -\endcode - -It may also be useful to refer to Fl_Window::current() -to get the window's size or position. - -\subsection osissues_icon_windows 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(const void *) - -\par -Sets the icon for the window to the passed pointer. You will -need to cast the \c HICON handle to a \c char* when -calling this method. To set the icon using an icon resource -compiled with your application use: -\code -window->icon((const void *)LoadIcon(fl_display, MAKEINTRESOURCE(IDI_ICON))); -\endcode - -\par -You can also use the \c LoadImage() and related -functions to load specific resolutions or create the icon from -bitmap data. - -<CENTER> -<TABLE WIDTH="90%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> -<TR> - <TD><B>NOTE:</B> - - You must call Fl_Window::show(int argc, char** argv) - for the icon to be used. The Fl_Window::show() method - does not bind the icon to the window. - - </TD> -</TR> -</TABLE> -</CENTER> - -\subsection osissues_msdos_console 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 \c WinMain() function that calls the -ANSI standard \c main() entry point for you. -<I> -This function creates a console window when you use the debug -version of the library. -</I> - -WIN32 applications without a console cannot write to -\c stdout or \c stderr, even if they are run from a -console window. Any output is silently thrown away. -Additionally, WIN32 applications are run in the background by -the console, although you can use "start /wait program" to run -them in the foreground. - -\subsection osissues_win32_problems Known WIN32 Bugs and Problems - -The following is a list of known bugs and problems in the WIN32 -version of FLTK: - -\li If a program is deactivated, <tt>Fl::wait()</tt> - 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. We were - 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. - -\li <tt>Fl_Gl_Window::can_do_overlay()</tt> returns true - until the first time it attempts to draw an overlay, and - then correctly returns whether or not there is overlay - hardware. - -\li <tt>SetCapture</tt> (used by <tt>Fl::grab()</tt>) - doesn't work, and the main window title bar turns gray - while menus are popped up. - -\li Compilation with <tt>gcc 3.4.4</tt> and <tt>-Os</tt> exposes an - optimisation bug in gcc. The symptom is that when drawing - filled circles only the perimeter is drawn. This can for instance - be seen in the symbols demo. Other optimisation options such - as -O2 and -O3 seem to work OK. More details can be found - in STR#1656 - -\section osissues_macos The Apple OS X Interface - -FLTK supports Apple OS X using the Apple Cocoa library. Older -versions of MacOS are no longer supported. - -Control, Option, and Command Modifier Keys - -\par -FLTK maps the Mac 'control' key to \c FL_CTRL, the -'option' key to \c FL_ALT and the 'Apple' key to -\c FL_META. Furthermore, \c FL_COMMAND designates the 'Apple' key on Mac OS X -and the 'control' key on other platforms. -Keyboard events return the key name in -Fl::event_key() and the keystroke translation in -Fl::event_text(). For example, typing Option-Y on a Mac -US keyboard will set \c FL_ALT in Fl::event_state(), -set Fl::event_key() to 'y' and return the Yen symbol in -Fl::event_text(). - -Apple "Quit" Event - -\par -When the user presses Cmd-Q or requests a termination of the -application, OS X will send a "Quit" Apple Event. FLTK handles -this event by sending an \c FL_CLOSE event to all open -windows. If all windows close, the application will terminate. - -Apple "Open" Event - -\par -Whenever the user drops a file onto an application icon, OS X -generates an Apple Event of the type "Open". You can have FLTK -notify you of an Open event by setting the \c fl_open_callback - -void fl_open_display() - -\par -Opens the display. Does nothing if it is already open. You should call -this if you wish to do Cocoa or Quartz calls and there is a chance that your -code will be called before the first \c show() of a window. - -Window fl_xid(const Fl_Window *) - -\par -Returns the window reference for an Fl_Window, or -\c NULL if the window has not been shown. This reference is a pointer -to an instance of the subclass FLWindow of Cocoa's NSWindow class. - -Fl_Window *fl_find(Window xid) - -\par -Returns the Fl_Window that corresponds to the given window reference, -or \c NULL if not found. FLTK windows that are children of top-level -windows share the \c Window of the top-level window. - -void \ref fl_open_callback(void (*cb)(const char *)) - -\par -\c cb will be called with a single Unix-style file name and path. -If multiple files were dropped, \c fl_open_callback() will be called -multiple times. - -void fl_mac_set_about( Fl_Callback *cb, void *user_data, int shortcut) - -\par -Attaches the callback \c cb to the "About myprog" item of the system application menu. -\c cb will be called with NULL first argument and \c user_data second argument. - -Fl_Sys_Menu_Bar class - -\par -The Fl_Sys_Menu_Bar class allows to build menu bars that, on Mac OS X, are -placed in the system menu bar (at top-left of display), and, on other platforms, -at a user-chosen location of a user-chosen window. - -\subsection osissues_quartz Drawing Things Using Quartz - -All code inside Fl_Widget::draw() -is expected to call Quartz drawing functions. The Quartz coordinate system -is flipped to match -FLTK's coordinate system. The origin for all drawing is in the top -left corner of the enclosing Fl_Window. The global variable -\c fl_gc is the appropriate Quartz 2D drawing environment. -Include FL/x.H to declare the \c fl_gc variable. - -Fl_Double_Window - -OS X double-buffers all windows automatically. On OS X, -Fl_Window and Fl_Double_Window are handled -internally in the same way. - -\subsection osissues_mac_files Mac File System Specifics - -\par Resource Forks - -FLTK does not access the resource fork of an application. -However, a minimal resource fork must be created for OS X -applications. Starting with OS X 10.6, resource forks are -no longer needed. - -<CENTER> -<TABLE WIDTH="80%" BORDER="1" BGCOLOR="#cccccc" CELLPADDING="5"> -<TR><TD><B>Caution (OS X 10.2 and older):</B> - -When using UNIX commands to copy or move executables, OS X -will NOT copy any resource forks! For copying and moving use -CpMac and MvMac respectively. For creating a tar archive, all -executables need to be stripped from their Resource Fork before -packing, e.g. "DeRez fluid > fluid.r". After unpacking the -Resource Fork needs to be reattached, e.g. "Rez fluid.r -o -fluid". -</TD></TR></TABLE> -</CENTER> - -It is advisable to use the Finder for moving and copying and -Mac archiving tools like Sit for distribution as they will -handle the Resource Fork correctly. - -\par Mac File Paths - -FLTK uses UTF-8-encoded UNIX-style filenames and paths. - -\sa group_macosx - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="forms.html"> - [Prev] - Forms Compatibility - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="migration_1_1.html"> - Migrating Code from FLTK 1.0 to 1.1 - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/positioner.png b/branch-3.0-2011/documentation/src/positioner.png Binary files differdeleted file mode 100644 index edc588a9f..000000000 --- a/branch-3.0-2011/documentation/src/positioner.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/preface.dox b/branch-3.0-2011/documentation/src/preface.dox deleted file mode 100644 index b065c6fc3..000000000 --- a/branch-3.0-2011/documentation/src/preface.dox +++ /dev/null @@ -1,112 +0,0 @@ -/** - - \page preface Preface - -This manual describes the Fast Light Tool Kit ("FLTK") -version 1.3.0, a C++ Graphical User Interface -("GUI") toolkit for UNIX, Microsoft Windows and Apple OS X. 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. - -<B>This manual may be printed, modified, and/or used under -the terms of the FLTK license provided in \ref license.</B> - -\section preface_organisation Organization - -This manual is organized into the following chapters and appendices: - -\li \ref intro -\li \ref basics -\li \ref common -\li \ref editor -\li \ref drawing -\li \ref events -\li \ref subclassing -\li \ref opengl -\li \ref fluid -\li \ref advanced -\li \ref unicode -\li \ref enumerations -\li \ref glut -\li \ref forms -\li \ref osissues -\li \ref migration_1_1 -\li \ref migration_1_3 -\li \ref development -\li \ref license -\li \ref examples - -\section preface_conventions Conventions - -This manual was generated using Doxygen -(see http://www.doxygen.org/) -to process the source code itself, special comments in the code, -and additional documentation files. -In general, Doxygen recognizes and denotes the following entities as shown: -- classes, such as Fl_Widget, -- methods, such as Fl_Widget::callback(Fl_Callback* cb, void* p), -- functions, such as fl_draw(const char *str, int x, int y), -- internal links, such as \ref preface_conventions, -- external links, such as http://www.stack.nl/~dimitri/doxygen/ - -Other code samples and commands are shown in <tt>regular courier type</tt>. - -\section preface_abbreviations Abbreviations - -The following abbreviations are used in this manual: - -\par X11 -The X Window System version 11. - -\par Xlib -The X Window System interface library. - -\par MS Windows, <tt>WIN32</tt> -The Microsoft Windows Application Programmer's Interface for Windows 2000, -Windows XP, Windows Vista, and Windows 7. FLTK uses the preprocessor definition -<tt>WIN32</tt> for the 32 bit and 64 bit MS Windows API. - -\par OS X, <tt>__APPLE__</tt> -The Apple desktop operating sytem OS X 10.0 and later. MacOS 8 and 9 support -was dropped after FLTK 1.0.10. FLTK uses the preprocessor definition -<tt>__APPLE__</tt> for OS X. - -\section preface_copyrights Copyrights and Trademarks - -FLTK is Copyright 1998-2010 by Bill Spitzak and others. Use and -distribution of FLTK is governed by the GNU Library General Public -License with 4 exceptions, located in \ref license. - -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. Apple, Macintosh, MacOS, and Mac OS X are -registered trademarks of Apple Computer, Inc. - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="main.html"> - [Prev] - Main Page - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="intro.html"> - Introduction to FLTK - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/resizebox1.png b/branch-3.0-2011/documentation/src/resizebox1.png Binary files differdeleted file mode 100644 index 3bb12ad53..000000000 --- a/branch-3.0-2011/documentation/src/resizebox1.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/resizebox2.png b/branch-3.0-2011/documentation/src/resizebox2.png Binary files differdeleted file mode 100644 index c8d4ce45e..000000000 --- a/branch-3.0-2011/documentation/src/resizebox2.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/round_clock.png b/branch-3.0-2011/documentation/src/round_clock.png Binary files differdeleted file mode 100644 index 43cc7d06a..000000000 --- a/branch-3.0-2011/documentation/src/round_clock.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/scrollbar.png b/branch-3.0-2011/documentation/src/scrollbar.png Binary files differdeleted file mode 100644 index f8d27fd43..000000000 --- a/branch-3.0-2011/documentation/src/scrollbar.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/slider.png b/branch-3.0-2011/documentation/src/slider.png Binary files differdeleted file mode 100644 index 51a7a169f..000000000 --- a/branch-3.0-2011/documentation/src/slider.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/subclassing.dox b/branch-3.0-2011/documentation/src/subclassing.dox deleted file mode 100644 index 3b6afb7e5..000000000 --- a/branch-3.0-2011/documentation/src/subclassing.dox +++ /dev/null @@ -1,565 +0,0 @@ -/** - - \page subclassing Adding and Extending Widgets - - -This chapter describes how to add your own widgets or extend existing -widgets in FLTK. - -\section subclassing_subclassing Subclassing - -New widgets are created by \e subclassing an existing FLTK widget, -typically Fl_Widget for controls and Fl_Group for composite widgets. - -A control widget typically interacts with the user to receive and/or -display a value of some sort. - -A composite widget holds a list of child widgets and handles moving, -sizing, showing, or hiding them as needed. Fl_Group is the main -composite widget class in FLTK, and all of the other composite widgets -(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. - -\section subclassing_fl_widget 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. - -\section subclassing_constructor The Constructor - -The constructor should have the following arguments: - -\code -MyClass(int x, int y, int w, int h, const char *label = 0); -\endcode - -This will allow the class to be used in -\ref fluid "FLUID" -without problems. - -The constructor must call the constructor for the base class and -pass the same arguments: - -\code -MyClass::MyClass(int x, int y, int w, int h, const char *label) -: Fl_Widget(x, y, w, h, label) { -// do initialization stuff... -} -\endcode - -Fl_Widget's protected constructor sets \p x(), \p y(), -\p w(), \p h(), and \p label() to the passed values -and initializes the other instance variables to: - -\code -type(0); -box(FL_NO_BOX); -color(FL_BACKGROUND_COLOR); -selection_color(FL_BACKGROUND_COLOR); -labeltype(FL_NORMAL_LABEL); -labelstyle(FL_NORMAL_STYLE); -labelsize(FL_NORMAL_SIZE); -labelcolor(FL_FOREGROUND_COLOR); -align(FL_ALIGN_CENTER); -callback(default_callback,0); -flags(ACTIVE|VISIBLE); -image(0); -deimage(0); -\endcode - -\section subclassing_protected Protected Methods of Fl_Widget - -The following methods are provided for subclasses to use: - -\li \ref subclassing_clear_visible "clear_visible()" -\li \ref subclassing_damage "damage()" -\li \ref subclassing_draw_box "draw_box()" -\li \ref subclassing_draw_focus "draw_focus()" -\li \ref subclassing_draw_label "draw_label()" -\li \ref subclassing_set_flag "set_flag()" -\li \ref subclassing_set_visible "set_visible()" -\li \ref subclassing_test_shortcut "test_shortcut()" -\li \ref subclassing_type "type()" - -\anchor subclassing_damage -void Fl_Widget::damage(uchar mask) <br> -void Fl_Widget::damage(uchar mask, int x, int y, int w, int h) <br> -uchar Fl_Widget::damage() - -\par -The first form indicates that a partial update of the object is -needed. The bits in mask are OR'd into -\ref subclassing_damage "damage()". -Your \p draw() routine can examine these bits to limit what it is -drawing. The public method Fl_Widget::redraw() simply does -\p Fl_Widget::damage(FL_DAMAGE_ALL), -but the implementation of your widget can call the public -\p damage(n). - -\par -The second form indicates that a region is damaged. If only these -calls are done in a window (no calls to \p 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 \p damage() unless this is a Fl_Window widget. - -\par -The third form returns the bitwise-OR of all \p damage(n) -calls done since the last \p draw(). - -\par -<I>When redrawing your widgets you should look at the damage bits to -see what parts of your widget need redrawing.</I> The \p handle() -method can then set individual damage bits to limit the amount of drawing -that needs to be done: -\code -MyClass::handle(int event) { - ... - if (change_to_part1) damage(1); - if (change_to_part2) damage(2); - if (change_to_part3) damage(4); -} - -MyClass::draw() { - if (damage() & FL_DAMAGE_ALL) { - ... draw frame/box and other static stuff ... - } - - if (damage() & (FL_DAMAGE_ALL | 1)) draw_part1(); - if (damage() & (FL_DAMAGE_ALL | 2)) draw_part2(); - if (damage() & (FL_DAMAGE_ALL | 4)) draw_part3(); -} -\endcode - -\todo Clarify Fl_Window::damage(n) handling - seems confused/wrong? - ORing value doesn't match setting behaviour in FL_Widget.H! - -\anchor subclassing_draw_box -void Fl_Widget::draw_box() const <br> -void Fl_Widget::draw_box(Fl_Boxtype t, Fl_Color c) const - -\par -The first form draws this widget's \p box(), using the -dimensions of the widget. The second form uses \p t as the box -type and \p c as the color for the box. - -\anchor subclassing_draw_focus -void Fl_Widget::draw_focus() <br> -void Fl_Widget::draw_focus(Fl_Boxtype t, int x, int y, int w, int h) const - -\par -Draws a focus box inside the widget's bounding box. The second -form allows you to specify a different bounding box. - -\anchor subclassing_draw_label -void Fl_Widget::draw_label() const <br> -void Fl_Widget::draw_label(int x, int y, int w, int h) const <br> -void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Align align) const - -\par -The first form is the usual function for a \p 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). - -\par -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, like a moving slider. - -\par -The third form draws the label anywhere. It acts as though -\p FL_ALIGN_INSIDE has been forced on so the label will appear inside -the passed bounding box. This is designed for parent groups to draw -labels with. - -\anchor subclassing_set_flag -void Fl_Widget::set_flag(int c) <br> - -\par -Calling \p set_flag(SHORTCUT_LABEL) modifies the behavior of -\ref subclassing_draw_label "draw_label()" so that '\&' characters -cause an underscore to be printed under the next letter. - -\anchor subclassing_clear_visible -\anchor subclassing_set_visible -void Fl_Widget::set_visible() <br> -void Fl_Widget::clear_visible() - -\par -Fast inline versions of Fl_Widget::hide() and Fl_Widget::show(). -These do not send the \p FL_HIDE and \p FL_SHOW events to the widget. - -\anchor subclassing_test_shortcut -int Fl_Widget::test_shortcut() <br> -static int Fl_Widget::test_shortcut(const char *s) - -\par -The first version tests Fl_Widget::label() against the current event -(which should be a \p FL_SHORTCUT event). If the label contains a '&' -character and the character after it matches the keypress, this returns -true. This returns false if the \p SHORTCUT_LABEL flag is off, if the -label is \p NULL, or does not have a '&' character in it, or if the -keypress does not match the character. - -\par -The second version lets you do this test against an arbitrary string. - -\todo Clarify Fl_Widget::test_shortcut() explanations. Fl_Widget.h - says Internal Use only, but subclassing chapter gives details! - -\anchor subclassing_type -uchar Fl_Widget::type() const <br> -void Fl_Widget::type(uchar t) - -\par -The property Fl_Widget::type() can return an arbitrary 8-bit -identifier, and can be set with the protected method <tt>type(uchar t)</tt>. -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. - -\par -FLTK does not use RTTI (Run Time Typing Information), to enhance -portability. But this may change in the near future if RTTI becomes -standard everywhere. - -\par -If you don't have RTTI you can use the clumsy FLTK mechanism, by -having \p type() use a unique value. These unique values must -be greater than the symbol \p FL_RESERVED_TYPE (which is 100) and -less than \p FL_WINDOW (unless you make a subclass of Fl_Window). -Look through the header files for \p FL_RESERVED_TYPE to find an -unused number. If you make a subclass of Fl_Window you must use -<tt>FL_WINDOW + n</tt> (where \p n must be in the range 1 to 7). - -\section subclassing_events Handling Events - -The virtual method Fl_Widget::handle(int event) is called -to handle each event passed to the widget. It can: - -\li Change the state of the widget. -\li Call Fl_Widget::redraw() if the widget needs to be redisplayed. -\li Call Fl_Widget::damage(uchar c) if the widget needs a partial-update - (assuming you provide support for this in your - \ref subclassing_drawing "draw()" - method). -\li Call Fl_Widget::do_callback() if a callback should be generated. -\li 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 acquired -by calling the -\ref events_event_xxx. -This information remains valid until another event is handled. - -Here is a sample \p handle() method for a widget that acts as -a pushbutton and also accepts the keystroke \p 'x' to cause the callback: - -\code -int MyClass::handle(int event) { - switch(event) { - case FL_PUSH: - highlight = 1; - redraw(); - return 1; - case FL_DRAG: { - int t = Fl::event_inside(this); - if (t != highlight) { - highlight = t; - redraw(); - } - } - return 1; - case FL_RELEASE: - if (highlight) { - highlight = 0; - redraw(); - do_callback(); - // never do anything after a callback, as the callback - // may delete the widget! - } - return 1; - case FL_SHORTCUT: - if (Fl::event_key() == 'x') { - do_callback(); - return 1; - } - return 0; - default: - return Fl_Widget::handle(event); - } -} -\endcode - -You must return non-zero if your \p handle() method -uses the event. If you return zero, the parent widget will try -sending the event to another widget. - -For debugging purposes, event numbers can be printed as their actual event names -using the \ref fl_eventnames[] array, e.g.: -\code - #include <FL/names.h> // defines fl_eventnames[] - [..] - int MyClass::handle(int e) { - printf("Event was %s (%d)\n", fl_eventnames[e], e); // e.g. "Event was FL_PUSH (1)" - [..] -\endcode - -\section subclassing_drawing Drawing the Widget - -The \p draw() virtual method is called when FLTK wants -you to redraw your widget. It will be called if and only if -\p damage() is non-zero, and \p damage() will be -cleared to zero after it returns. The \p draw() method -should be declared protected so that it can't be called from -non-drawing code. - -The \p damage() value contains the bitwise-OR of all -the \p 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 on the -\p FL_DAMAGE_ALL bit if it thinks the entire widget must -be redrawn, e.g. for an expose event. - -Expose events (and the -\ref subclassing_damage "damage(mask,x,y,w,h)" function described -above) will cause \p draw() to be called with FLTK's -\ref ssect_Clipping "clipping" -turned on. You can greatly speed up redrawing in some -cases by testing \p fl_not_clipped(x,y,w,h) or \p %fl_clip_box() -and skipping invisible parts. - -Besides the protected methods described above, FLTK provides a large -number of basic drawing functions, which are described in the chapter -\ref drawing. - -\section subclassing_resizing Resizing the Widget - -The \p resize(x,y,w,h) method is called when -the widget is being resized or moved. The arguments are the new -position, width, and height. \p x(), \p y(), \p w(), -and \p h() still remain the old size. You must call \p resize() -on your base class with the same arguments to get the widget size to -actually change. - -This should \e not call \p redraw(), at least if only the -\p x() and \p y() change. This is because composite widgets like -Fl_Scroll may have a more efficient way of drawing the new position. - -\section subclassing_composite Making a Composite Widget - -A "composite" widget contains one or more "child" widgets. -To make a composite widget 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: - -\code -class MyClass : public Fl_Group { - Fl_Button the_button; - Fl_Slider the_slider; - ... -}; -\endcode - -The constructor has to initialize these instances. They are automatically -added to the group, since the Fl_Group constructor does -Fl_Group::begin(). -<I>Don't forget to call Fl_Group::end() or use the Fl_End pseudo-class:</I> - -\code -MyClass::MyClass(int x, int y, int w, int h) : - Fl_Group(x, y, w, h), - the_button(x + 5, y + 5, 100, 20), - the_slider(x, y + 50, w, 20) -{ - ...(you could add dynamically created child widgets here)... - end(); // don't forget to do this! -} -\endcode - -The child widgets need callbacks. These will be called with a pointer -to the children, but the widget itself may be found in the \p parent() -pointer of the child. Usually these callbacks can be static private -methods, with a matching private method: - -\code -void MyClass::static_slider_cb(Fl_Widget* v, void *) { // static method - ((MyClass*)(v->parent())->slider_cb(); -} -void MyClass::slider_cb() { // normal method - use(the_slider->value()); -} -\endcode - -If you make the \p handle() method, you can quickly pass all the -events to the children using the Fl_Group::handle() method. -You don't need to override \p handle() if your composite widget -does nothing other than pass events to the children: - -\code -int MyClass::handle(int event) { - if (Fl_Group::handle(event)) return 1; - ... handle events that children don't want ... -} -\endcode - -If you override \p draw() you need to draw all the children. -If \p redraw() or \p damage() is called on a child, -\p damage(FL_DAMAGE_CHILD) is done to the group, -so this bit of \p 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: - -\code -int MyClass::draw() { - Fl_Widget *const*a = array(); - if (damage() == FL_DAMAGE_CHILD) { // only redraw some children - for (int i = children(); i --; a ++) update_child(**a); - } else { // total redraw - ... draw background graphics ... - // now draw all the children atop the background: - for (int i = children_; i --; a ++) { - draw_child(**a); - draw_outside_label(**a); // you may not need to do this - } - } -} -\endcode - -Fl_Group provides some protected methods to make drawing easier: - -\li \ref subclassing_draw_child "draw_child()" -\li \ref subclassing_draw_children "draw_children()" -\li \ref subclassing_draw_outside_label "draw_outside_label()" -\li \ref subclassing_update_child "update_child()" - -\anchor subclassing_draw_child -void Fl_Group::draw_child(Fl_Widget &widget) const - -\par -This will force the child's \p damage() bits all to one and call -\p draw() on it, then clear the \p 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 \p visible() or if it is -clipped. - -\anchor subclassing_draw_children -void Fl_Group::draw_children() - -\par -A convenience function that draws all children of the group. -This is useful if you derived a widget from Fl_Group and want to draw -a special border or background. You can call \p draw_children() from the -derived \p draw() method after drawing the box, border, or background. - -\anchor subclassing_draw_outside_label -void Fl_Group::draw_outside_label(const Fl_Widget &widget) const - -\par -Draw the labels that are \e not drawn by -\ref subclassing_draw_label "draw_label()". -If you want more control over the label positions you might want to call -<tt>child->draw_label(x,y,w,h,a)</tt>. - -\anchor subclassing_update_child -void Fl_Group::update_child(Fl_Widget& widget) const - -\par -Draws the child only if its \p damage() is non-zero. You -should call this on all the children if your own damage is equal to -\p FL_DAMAGE_CHILD. Nothing is done if the child is not \p visible() -or if it is clipped. - -\section subclassing_cutnpaste Cut and Paste Support - -FLTK provides routines to cut and paste 8-bit text (in the future this -may be UTF-8) between applications: - -\li Fl::paste() -\li Fl::selection() -\li Fl::selection_owner() - -It may be possible to cut/paste non-text data by using Fl::add_handler(). -Note that handling events beyond those provided by FLTK may be operating -system specific. See \ref osissues for more details. - -\section subclassing_dragndrop Drag And Drop Support - -FLTK provides routines to drag and drop 8-bit text between applications: - -Drag'n'drop operations are initiated by copying data to the -clipboard and calling the function Fl::dnd(). - -Drop attempts are handled via the following events, -already described under \ref events_dnd in a previous chapter: - -\li \p FL_DND_ENTER -\li \p FL_DND_DRAG -\li \p FL_DND_LEAVE -\li \p FL_DND_RELEASE -\li \p FL_PASTE - -\section subclassing_fl_window Making a subclass of Fl_Window - -You may want your widget to be a subclass of -Fl_Window, Fl_Double_Window, or -Fl_Gl_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_Group, and in fact you can easily -switch a subclass back and forth. Watch out for the following -differences: - --# Fl_Window is a subclass of Fl_Group so - <I>make sure your constructor calls</I> \p end() - unless you actually want children added to your window. --# When handling events and drawing, the upper-left corner is at - 0,0, not <tt>x(),y()</tt> as in other Fl_Widget's. - For instance, to draw a box around the widget, call - <tt>draw_box(0,0,w(),h())</tt>, rather than - <tt>draw_box(x(),y(),w(),h())</tt>. - -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 the -\ref osissues chapter for more information. - - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="events.html"> - [Prev] - Handling Events - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="opengl.html"> - Using OpenGL - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/sudoku.man b/branch-3.0-2011/documentation/src/sudoku.man deleted file mode 100644 index 32d496e8e..000000000 --- a/branch-3.0-2011/documentation/src/sudoku.man +++ /dev/null @@ -1,33 +0,0 @@ -.TH sudoku 6 "FLTK Sudoku" "15 January 2006" -.SH NAME -sudoku \- the fltk sudoku game -.sp -.SH SYNOPSIS -\fISudoku\fR is a FLTK-based version of the game of Sudoku. -Sudoku (pronounced soo-dough-coo with the emphasis on the first -syllable) is a simple number-based puzzle/game played on a 9x9 -grid that is divided into 3x3 subgrids. The goal is to enter a -number from 1 to 9 in each cell so that each number appears only -once in each column and row. -.LP -At the start of a new game, Sudoku fills in a random selection of -cells for you - the number of cells depends on the difficulty -level you use. Click in any of the empty cells or use the arrow -keys to highlight individual cells and press a number from 1 to 9 -to fill in the cell. To clear a cell, press 0, Delete, or -Backspace. As you complete each subgrid, correct subgrids are -highlighted in green. When you have successfully completed all -subgrids, the entire puzzle is highlighted until you start a new -game. -.LP -As you work to complete the puzzle, you can display possible -solutions inside each cell by holding the Shift key and pressing -each number in turn. Repeat the process to remove individual -numbers, or press a number without the Shift key to replace them -with the actual number to use. -.SH SEE ALSO -fltk(3) -.br -FLTK Web Site, http://www.fltk.org/ -.SH AUTHOR -Michael R Sweet. diff --git a/branch-3.0-2011/documentation/src/symbols.png b/branch-3.0-2011/documentation/src/symbols.png Binary files differdeleted file mode 100644 index 1a81280e3..000000000 --- a/branch-3.0-2011/documentation/src/symbols.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/table-as-container.png b/branch-3.0-2011/documentation/src/table-as-container.png Binary files differdeleted file mode 100644 index 1a7482302..000000000 --- a/branch-3.0-2011/documentation/src/table-as-container.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/table-dimensions.png b/branch-3.0-2011/documentation/src/table-dimensions.png Binary files differdeleted file mode 100644 index 46b7e9005..000000000 --- a/branch-3.0-2011/documentation/src/table-dimensions.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/table-simple.png b/branch-3.0-2011/documentation/src/table-simple.png Binary files differdeleted file mode 100644 index b54d883b1..000000000 --- a/branch-3.0-2011/documentation/src/table-simple.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/tabs.png b/branch-3.0-2011/documentation/src/tabs.png Binary files differdeleted file mode 100644 index 81f2a8390..000000000 --- a/branch-3.0-2011/documentation/src/tabs.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/text.png b/branch-3.0-2011/documentation/src/text.png Binary files differdeleted file mode 100644 index fb073fc2d..000000000 --- a/branch-3.0-2011/documentation/src/text.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/tiny.png b/branch-3.0-2011/documentation/src/tiny.png Binary files differdeleted file mode 100644 index 133ecd10e..000000000 --- a/branch-3.0-2011/documentation/src/tiny.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/tree-elements.png b/branch-3.0-2011/documentation/src/tree-elements.png Binary files differdeleted file mode 100644 index 552159b48..000000000 --- a/branch-3.0-2011/documentation/src/tree-elements.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/unicode.dox b/branch-3.0-2011/documentation/src/unicode.dox deleted file mode 100644 index f1a6e4cf3..000000000 --- a/branch-3.0-2011/documentation/src/unicode.dox +++ /dev/null @@ -1,520 +0,0 @@ -/** - - \page unicode Unicode and UTF-8 Support - -This chapter explains how FLTK handles international -text via Unicode and UTF-8. - -Unicode support was only recently added to FLTK and is -still incomplete. This chapter is Work in Progress, reflecting -the current state of Unicode support. - -\section unicode_about About Unicode, ISO 10646 and UTF-8 - -The summary of Unicode, ISO 10646 and UTF-8 given below is -deliberately brief, and provides just enough information for -the rest of this chapter. -For further information, please see: -- http://www.unicode.org -- http://www.iso.org -- http://en.wikipedia.org/wiki/Unicode -- http://www.cl.cam.ac.uk/~mgk25/unicode.html -- http://www.apps.ietf.org/rfc/rfc3629.html - -\par The Unicode Standard - -The Unicode Standard was originally developed by a consortium of mainly -US computer manufacturers and developers of multi-lingual software. -It has now become a defacto standard for character encoding, -and is supported by most of the major computing companies in the world. - -Before Unicode, many different systems, on different platforms, -had been developed for encoding characters for different languages, -but no single encoding could satisfy all languages. -Unicode provides access to over 100,000 characters -used in all the major languages written today, -and is independent of platform and language. - -Unicode also provides higher-level concepts needed for text processing -and typographic publishing systems, such as algorithms for sorting and -comparing text, composite character and text rendering, right-to-left -and bi-directional text handling. - -<i>There are currently no plans to add this extra functionality to FLTK.</i> - -\par ISO 10646 - -The International Organisation for Standardization (ISO) had also -been trying to develop a single unified character set. -Although both ISO and the Unicode Consortium continue to publish -their own standards, they have agreed to coordinate their work so -that specific versions of the Unicode and ISO 10646 standards are -compatible with each other. - -The international standard ISO 10646 defines the -<b>Universal Character Set</b> (UCS) -which contains the characters required for almost all known languages. -The standard also defines three different implementation levels specifying -how these characters can be combined. - -<i>There are currently no plans for handling the different implementation -levels or the combining characters in FLTK.</i> - -In UCS, characters have a unique numerical code and an official name, -and are usually shown using 'U+' and the code in hexadecimal, -e.g. U+0041 is the "Latin capital letter A". -The UCS characters U+0000 to U+007F correspond to US-ASCII, -and U+0000 to U+00FF correspond to ISO 8859-1 (Latin1). - -ISO 10646 was originally designed to handle a 31-bit character set -from U+00000000 to U+7FFFFFFF, but the current idea is that 21-bits -will be sufficient for all future needs, giving characters up to -U+10FFFF. The complete character set is sub-divided into \e planes. -<i>Plane 0</i>, also known as the <b>Basic Multilingual Plane</b> -(BMP), ranges from U+0000 to U+FFFD and consists of the most commonly -used characters from previous encoding standards. Other planes -contain characters for specialist applications. -\todo -Do we need this info about planes? - -The UCS also defines various methods of encoding characters as -a sequence of bytes. -UCS-2 encodes Unicode characters into two bytes, -which is wasteful if you are only dealing with ASCII or Latin1 text, -and insufficient if you need characters above U+00FFFF. -UCS-4 uses four bytes, which lets it handle higher characters, -but this is even more wasteful for ASCII or Latin1. - -\par UTF-8 - -The Unicode standard defines various UCS Transformation Formats. -UTF-16 and UTF-32 are based on units of two and four bytes. -UCS characters requiring more than 16-bits are encoded using -"surrogate pairs" in UTF-16. - -UTF-8 encodes all Unicode characters into variable length -sequences of bytes. Unicode characters in the 7-bit ASCII -range map to the same value and are represented as a single byte, -making the transformation to Unicode quick and easy. - -All UCS characters above U+007F are encoded as a sequence of -several bytes. The top bits of the first byte are set to show -the length of the byte sequence, and subseqent bytes are -always in the range 0x80 to 0x8F. This combination provides -some level of synchronisation and error detection. - -<table summary="Unicode character byte sequences" align="center"> -<tr> - <td>Unicode range</td> - <td>Byte sequences</td> -</tr> -<tr> - <td><tt>U+00000000 - U+0000007F</tt></td> - <td><tt>0xxxxxxx</tt></td> -</tr> -<tr> - <td><tt>U+00000080 - U+000007FF</tt></td> - <td><tt>110xxxxx 10xxxxxx</tt></td> -</tr> -<tr> - <td><tt>U+00000800 - U+0000FFFF</tt></td> - <td><tt>1110xxxx 10xxxxxx 10xxxxxx</tt></td> -</tr> -<tr> - <td><tt>U+00010000 - U+001FFFFF</tt></td> - <td><tt>11110xxx 10xxxxxx 10xxxxxx 10xxxxxx</tt></td> -</tr> -<tr> - <td><tt>U+00200000 - U+03FFFFFF</tt></td> - <td><tt>111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx</tt></td> -</tr> -<tr> - <td><tt>U+04000000 - U+7FFFFFFF</tt></td> - <td><tt>1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx</tt></td> -</tr> -</table> - -Moving from ASCII encoding to Unicode will allow all new FLTK -applications to be easily internationalized and used all -over the world. By choosing UTF-8 encoding, FLTK remains -largely source-code compatible to previous iteration of the -library. - -\section unicode_in_fltk Unicode in FLTK - -\todo -Work through the code and this documentation to harmonize -the [<b>OksiD</b>] and [<b>fltk2</b>] functions. - -FLTK will be entirely converted to Unicode using UTF-8 encoding. -If a different encoding is required by the underlying operating -system, FLTK will convert the string as needed. - -It is important to note that the initial implementation of -Unicode and UTF-8 in FLTK involves three important areas: - -- provision of Unicode character tables and some simple related functions; - -- conversion of char* variables and function parameters from single byte - per character representation to UTF-8 variable length sequences; - -- modifications to the display font interface to accept general - Unicode character or UCS code numbers instead of just ASCII or Latin1 - characters. - -The current implementation of Unicode / UTF-8 in FLTK will impose -the following limitations: - -- An implementation note in the [<b>OksiD</b>] code says that all functions - are LIMITED to 24 bit Unicode values, but also says that only 16 bits - are really used under linux and win32. - <b>[Can we verify this?]</b> - -- The [<b>fltk2</b>] %fl_utf8encode() and %fl_utf8decode() functions are - designed to handle Unicode characters in the range U+000000 to U+10FFFF - inclusive, which covers all UTF-16 characters, as specified in RFC 3629. - <i>Note that the user must first convert UTF-16 surrogate pairs to UCS.</i> - -- FLTK will only handle single characters, so composed characters - consisting of a base character and floating accent characters - will be treated as multiple characters; - -- FLTK will only compare or sort strings on a byte by byte basis - and not on a general Unicode character basis; - -- FLTK will not handle right-to-left or bi-directional text; - - \todo - Verify 16/24 bit Unicode limit for different character sets? - OksiD's code appears limited to 16-bit whereas the FLTK2 code - appears to handle a wider set. What about illegal characters? - See comments in %fl_utf8fromwc() and %fl_utf8toUtf16(). - -\section unicode_illegals Illegal Unicode and UTF-8 sequences - -Three pre-processor variables are defined in the source code that -determine how %fl_utf8decode() handles illegal UTF-8 sequences: - -- if ERRORS_TO_CP1252 is set to 1 (the default), %fl_utf8decode() will - assume that a byte sequence starting with a byte in the range 0x80 - to 0x9f represents a Microsoft CP1252 character, and will instead - return the value of an equivalent UCS character. Otherwise, it - will be processed as an illegal byte value as described below. - -- if STRICT_RFC3629 is set to 1 (not the default!) then UTF-8 - sequences that correspond to illegal UCS values are treated as - errors. Illegal UCS values include those above U+10FFFF, or - corresponding to UTF-16 surrogate pairs. Illegal byte values - are handled as described below. - -- if ERRORS_TO_ISO8859_1 is set to 1 (the default), the illegal - byte value is returned unchanged, otherwise 0xFFFD, the Unicode - REPLACEMENT CHARACTER, is returned instead. - -%fl_utf8encode() is less strict, and only generates the UTF-8 -sequence for 0xFFFD, the Unicode REPLACEMENT CHARACTER, if it is -asked to encode a UCS value above U+10FFFF. - -Many of the [<b>fltk2</b>] functions below use %fl_utf8decode() and -%fl_utf8encode() in their own implementation, and are therefore -somewhat protected from bad UTF-8 sequences. - -The [<b>OksiD</b>] %fl_utf8len() function assumes that the byte it is -passed is the first byte in a UTF-8 sequence, and returns the length -of the sequence. Trailing bytes in a UTF-8 sequence will return -1. - -- \b WARNING: - %fl_utf8len() can not distinguish between single - bytes representing Microsoft CP1252 characters 0x80-0x9f and - those forming part of a valid UTF-8 sequence. You are strongly - advised not to use %fl_utf8len() in your own code unless you - know that the byte sequence contains only valid UTF-8 sequences. - -- \b WARNING: - Some of the [OksiD] functions below use still use %fl_utf8len() in - their implementations. These may need further validation. - -Please see the individual function description for further details -about error handling and return values. - -\section unicode_fltk_calls FLTK Unicode and UTF-8 functions - -This section currently provides a brief overview of the functions. -For more details, consult the main text for each function via its link. - -int fl_utf8locale() - \b FLTK2 - <br> -\par -\p %fl_utf8locale() returns true if the "locale" seems to indicate -that UTF-8 encoding is used. -\par -<i>It is highly recommended that your change your system so this does return -true!</i> - - -int fl_utf8test(const char *src, unsigned len) - \b FLTK2 - <br> -\par -\p %fl_utf8test() examines the first \p len bytes of \p src. -It returns 0 if there are any illegal UTF-8 sequences; -1 if \p src contains plain ASCII or if \p len is zero; -or 2, 3 or 4 to indicate the range of Unicode characters found. - - -int fl_utf_nb_char(const unsigned char *buf, int len) - \b OksiD - <br> -\par -Returns the number of UTF-8 character in the first \p len bytes of \p buf. - - -int fl_unichar_to_utf8_size(Fl_Unichar) - <br> -int fl_utf8bytes(unsigned ucs) - <br> -\par -Returns the number of bytes needed to encode \p ucs in UTF-8. - - -int fl_utf8len(char c) - \b OksiD - <br> -\par -If \p c is a valid first byte of a UTF-8 encoded character sequence, -\p %fl_utf8len() will return the number of bytes in that sequence. -It returns -1 if \p c is not a valid first byte. - - -unsigned int fl_nonspacing(unsigned int ucs) - \b OksiD - <br> -\par -Returns true if \p ucs is a non-spacing character. -<b>[What are non-spacing characters?]</b> - - -const char* fl_utf8back(const char *p, const char *start, const char *end) - \b FLTK2 - <br> -const char* fl_utf8fwd(const char *p, const char *start, const char *end) - \b FLTK2 - <br> -\par -If \p p already points to the start of a UTF-8 character sequence, -these functions will return \p p. -Otherwise \p %fl_utf8back() searches backwards from \p p -and \p %fl_utf8fwd() searches forwards from \p p, -within the \p start and \p end limits, -looking for the start of a UTF-8 character. - - -unsigned int fl_utf8decode(const char *p, const char *end, int *len) - \b FLTK2 - <br> -int fl_utf8encode(unsigned ucs, char *buf) - \b FLTK2 - <br> -\par -\p %fl_utf8decode() attempts to decode the UTF-8 character that starts -at \p p and may not extend past \p end. -It returns the Unicode value, and the length of the UTF-8 character sequence -is returned via the \p len argument. -\p %fl_utf8encode() writes the UTF-8 encoding of \p ucs into \p buf -and returns the number of bytes in the sequence. -See the main documentation for the treatment of illegal Unicode -and UTF-8 sequences. - - -unsigned int fl_utf8froma(char *dst, unsigned dstlen, const char *src, unsigned srclen) - \b FLTK2 - <br> -unsigned int fl_utf8toa(const char *src, unsigned srclen, char *dst, unsigned dstlen) - \b FLTK2 - <br> -\par -\p %fl_utf8froma() converts a character string containing single bytes -per character (i.e. ASCII or ISO-8859-1) into UTF-8. -If the \p src string contains only ASCII characters, the return value will -be the same as \p srclen. -\par -\p %fl_utf8toa() converts a string containing UTF-8 characters into -single byte characters. UTF-8 characters do not correspond to ASCII -or ISO-8859-1 characters below 0xFF are replaced with '?'. - -\par -Both functions return the number of bytes that would be written, not -counting the null terminator. -\p destlen provides a means of limiting the number of bytes written, -so setting \p destlen to zero is a means of measuring how much storage -would be needed before doing the real conversion. - - -char* fl_utf2mbcs(const char *src) - \b OksiD - <br> -\par -converts a UTF-8 string to a local multi-byte character string. -<b>[More info required here!]</b> - -unsigned int fl_utf8fromwc(char *dst, unsigned dstlen, const wchar_t *src, unsigned srclen) - \b FLTK2 - <br> -unsigned int fl_utf8towc(const char *src, unsigned srclen, wchar_t *dst, unsigned dstlen) - \b FLTK2 - <br> -unsigned int fl_utf8toUtf16(const char *src, unsigned srclen, unsigned short *dst, unsigned dstlen) - \b FLTK2 - <br> -\par -These routines convert between UTF-8 and \p wchar_t or "wide character" -strings. -The difficulty lies in the fact \p sizeof(wchar_t) is 2 on Windows -and 4 on Linux and most other systems. -Therefore some "wide characters" on Windows may be represented -as "surrogate pairs" of more than one \p wchar_t. - -\par -\p %fl_utf8fromwc() converts from a "wide character" string to UTF-8. -Note that \p srclen is the number of \p wchar_t elements in the source -string and on Windows and this might be larger than the number of characters. -\p dstlen specifies the maximum number of \b bytes to copy, including -the null terminator. - -\par -\p %fl_utf8towc() converts a UTF-8 string into a "wide character" string. -Note that on Windows, some "wide characters" might result in "surrogate -pairs" and therefore the return value might be more than the number of -characters. -\p dstlen specifies the maximum number of \b wchar_t elements to copy, -including a zero terminating element. -<b>[Is this all worded correctly?]</b> - -\par -\p %fl_utf8toUtf16() converts a UTF-8 string into a "wide character" -string using UTF-16 encoding to handle the "surrogate pairs" on Windows. -\p dstlen specifies the maximum number of \b wchar_t elements to copy, -including a zero terminating element. -<b>[Is this all worded correctly?]</b> - -\par -These routines all return the number of elements that would be required -for a full conversion of the \p src string, including the zero terminator. -Therefore setting \p dstlen to zero is a way of measuring how much storage -would be needed before doing the real conversion. - - -unsigned int fl_utf8from_mb(char *dst, unsigned dstlen, const char *src, unsigned srclen) - \b FLTK2 - <br> -unsigned int fl_utf8to_mb(const char *src, unsigned srclen, char *dst, unsigned dstlen) - \b FLTK2 - <br> -\par -These functions convert between UTF-8 and the locale-specific multi-byte -encodings used on some systems for filenames, etc. -If fl_utf8locale() returns true, these functions don't do anything useful. -<b>[Is this all worded correctly?]</b> - - -int fl_tolower(unsigned int ucs) - \b OksiD - <br> -int fl_toupper(unsigned int ucs) - \b OksiD - <br> -int fl_utf_tolower(const unsigned char *str, int len, char *buf) - \b OksiD - <br> -int fl_utf_toupper(const unsigned char *str, int len, char *buf) - \b OksiD - <br> -\par -\p %fl_tolower() and \p %fl_toupper() convert a single Unicode character -from upper to lower case, and vice versa. -\p %fl_utf_tolower() and \p %fl_utf_toupper() convert a string of bytes, -some of which may be multi-byte UTF-8 encodings of Unicode characters, -from upper to lower case, and vice versa. -\par -Warning: to be safe, \p buf length must be at least \p 3*len -[for 16-bit Unicode] - - -int fl_utf_strcasecmp(const char *s1, const char *s2) - \b OksiD - <br> -int fl_utf_strncasecmp(const char *s1, const char *s2, int n) - \b OksiD - <br> -\par -\p %fl_utf_strcasecmp() is a UTF-8 aware string comparison function that -converts the strings to lower case Unicode as part of the comparison. -\p %flt_utf_strncasecmp() only compares the first \p n characters [bytes?] - - -\section unicode_system_calls FLTK Unicode versions of system calls - -- int fl_access(const char* f, int mode) - \b OksiD -- int fl_chmod(const char* f, int mode) - \b OksiD -- int fl_execvp(const char* file, char* const* argv) - \b OksiD -- FILE* fl_fopen(cont char* f, const char* mode) - \b OksiD -- char* fl_getcwd(char* buf, int maxlen) - \b OksiD -- char* fl_getenv(const char* name) - \b OksiD -- char fl_make_path(const char* path) - returns char ? - \b OksiD -- void fl_make_path_for_file(const char* path) - \b OksiD -- int fl_mkdir(const char* f, int mode) - \b OksiD -- int fl_open(const char* f, int o, ...) - \b OksiD -- int fl_rename(const char* f, const char* t) - \b OksiD -- int fl_rmdir(const char* f) - \b OksiD -- int fl_stat(const char* path, struct stat* buffer) - \b OksiD -- int fl_system(const char* f) - \b OksiD -- int fl_unlink(const char* f) - \b OksiD - -\par TODO: - -\li more doc on unicode, add links -\li write something about filename encoding on OS X... -\li explain the fl_utf8_... commands -\li explain issues with Fl_Preferences -\li why FLTK has no Fl_String class - -\htmlonly -<hr> -<table summary="navigation bar" width="100%" border="0"> -<tr> - <td width="45%" align="LEFT"> - <a class="el" href="advanced.html"> - [Prev] - Advanced FLTK - </a> - </td> - <td width="10%" align="CENTER"> - <a class="el" href="main.html">[Index]</a> - </td> - <td width="45%" align="RIGHT"> - <a class="el" href="enumerations.html"> - FLTK Enumerations - [Next] - </a> - </td> -</tr> -</table> -\endhtmlonly - -*/ diff --git a/branch-3.0-2011/documentation/src/valuators.png b/branch-3.0-2011/documentation/src/valuators.png Binary files differdeleted file mode 100644 index e2fd68472..000000000 --- a/branch-3.0-2011/documentation/src/valuators.png +++ /dev/null diff --git a/branch-3.0-2011/documentation/src/value_slider.png b/branch-3.0-2011/documentation/src/value_slider.png Binary files differdeleted file mode 100644 index 989ee11ee..000000000 --- a/branch-3.0-2011/documentation/src/value_slider.png +++ /dev/null |
