384929e7d2
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@7628 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
114 lines
4.4 KiB
Plaintext
114 lines
4.4 KiB
Plaintext
FLTK EXAMPLE PROGRAMS
|
|
---------------------
|
|
|
|
This directory contains example FLTK programs that demonstrate
|
|
recommended programming practices and techniques for FLTK application
|
|
programmers. The "*-simple.cxx" files are a good starting point for
|
|
those new to FLTK.
|
|
|
|
The programs in this directory are NOT built automatically
|
|
when you build FLTK; you have to manually build them.
|
|
|
|
The goals of these example programs:
|
|
|
|
o Show good programming style for app programmers to emulate
|
|
|
|
o Show simple examples of how to use widgets to new users of FLTK.
|
|
|
|
o Show intermediate or advanced examples that show particular
|
|
techniques often misused or hard to document
|
|
|
|
o Demonstrate code that are FAQs on the newsgroup forum.
|
|
(such as how to use threads, callbacks, etc)
|
|
|
|
o Example code should be short, but not at the expense of clarity.
|
|
|
|
o Where possible, examples should emphasize FLTK's simplicity.
|
|
|
|
|
|
NEW SUBMISSIONS: RECOMMENDED PRACTICES
|
|
|
|
These programs must follow FLTK coding style as defined in the FLTK
|
|
"CMP" (Configuration Management Plan/Coding Standards).
|
|
|
|
Example code should demonstrate recommended techniques the FLTK
|
|
developers think application programmers should use in their own
|
|
applications.
|
|
|
|
The best examples are those that are as short and clear as possible;
|
|
terse, but not at the expense of clarity.
|
|
|
|
To avoid cluttering up the top level directory with ancillary files
|
|
(such as image files or icons), examples that depend on more than
|
|
just a .cxx/.h file pair should have their own subdirectory.
|
|
|
|
Data files common to several examples should be located in the
|
|
examples/data directory.
|
|
|
|
Ancillary data files should be as small as possible, to keep the
|
|
distribution tar files small. Avoid high resolution images or
|
|
uncompressed images when possible.
|
|
|
|
Examples that need very large data sets should not be part of the
|
|
FLTK distribution; they can be provided as separate packages
|
|
(eg. as articles or external links).
|
|
|
|
Some widgets have multiple common uses that are best demonstrated
|
|
separately. For instance, the table widget can be used as a
|
|
custom data table, or as a spreadsheet, or as a widget container.
|
|
So separate examples for each would be e.g. "table-custom-data.cxx",
|
|
"table-spreadsheet.cxx", "table-widget-container.cxx", etc.
|
|
|
|
Example programs should contain comments that help understand the
|
|
concepts shown, but not so verbose as to dwarf the code or make
|
|
the code hard to read. Within code, it's best to use single line
|
|
comments to emphasize code that might be unclear. Let the code
|
|
speak as much as possible.
|
|
|
|
Examples programs may be referred to from the documentation
|
|
as good examples on how to do particular programming techniques.
|
|
|
|
|
|
NAMING CONVENTIONS
|
|
|
|
Example programs that demonstrate a particular widget should start
|
|
with that widget's name in lowercase, eg. "table.cxx" for Fl_Table.
|
|
|
|
Demonstrations of a particular technique should start with
|
|
"howto-xxx.cxx" to avoid naming conflicts with future widgets
|
|
of the same name.
|
|
|
|
xxx-simple.cxx -- Simplest possible example of widget xxx
|
|
eg. table-simple.cxx
|
|
|
|
xxx-<technique>.cxx -- A particular "technique" using widget xxx
|
|
eg. "table-spreadsheet.cxx"
|
|
|
|
howto-<technique>.cxx -- Demonstrate a particular technique, eg. "howto-threading.cxx"
|
|
|
|
Some example programs may depend on multiple files. To avoid
|
|
cluttering up the top level examples directory, such examples will
|
|
have their own subdirectory with the files they depend on localized
|
|
to that directory.
|
|
|
|
Example programs should be as small as possible, to keep the
|
|
distribution tar files small.
|
|
|
|
Very large examples, or examples that depend on large data sets
|
|
should be submitted as separate articles on the FLTK site, or as
|
|
external links on the FLTK site's 'links' page.
|
|
|
|
|
|
HISTORY
|
|
|
|
Previous to FLTK 1.3.0, the fltk/test directory served the dual
|
|
purpose of containing test suites as well as example code.
|
|
|
|
But the fltk/test programs started becoming necessarily complex,
|
|
testing for obscure problems, and not necessarily good demos for
|
|
applications programmers.
|
|
|
|
The fltk/examples directory was created in FLTK 1.3.0 to separate
|
|
'good programming examples' from the test suite code.
|
|
|