fltk/documentation/development.dox
Albrecht Schlosser 82e80a4fa0 Added navigation bar.
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6352 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
2008-09-28 23:24:36 +00:00

398 lines
11 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/**
\page development I - Developer Information
<P>This chapter describes FLTK development and documentation.
</P>
\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.gif
\image html round_clock.gif
#/
/##
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
&quot;, &uuml;, &ccedil;, &Ccedil;, but not all HTML quoting characters.
\endcode
This will appear in the document:
Doxygen understands many HTML quoting characters like
&quot;, &uuml;, &ccedil;, &Ccedil;, 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 "&cedil;").
\#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 "&cedil;").
\#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
\li normal HTML links
\li HTML links without markup - doxygen creates "http://..."
links automatically
\li links to other doxygen chapters with the \\ref statments
\li links to named sections within the same or other doxygen chapters,
if they are defined there with a \\section statement
\code
see chapter \ref unicode creates a link to the named chapter unicode
that has been created with a \subpage statement.
see <a href="drawing.html#character_encoding">chapter 5</a> creates
a link to a named html anchor "character_encoding" within the same file.
For further informations about quoting see
http://www.stack.nl/~dimitri/doxygen/htmlcmds.html
Bold link text: you can see the <b>\e old online documentation</b>
of FLTK 1.3 at \b http://www.fltk.org/doc-1.3/toc.html
see section \ref development_non-ascii
\endcode
appears as:
see chapter \ref unicode creates a link to the named chapter unicode
that has been created with a \\subpage statement.
see <a href="drawing.html#character_encoding">chapter 5</a> creates
a link to a named html anchor "character_encoding" within the same file.
For further informations about quoting see
http://www.stack.nl/~dimitri/doxygen/htmlcmds.html
Bold link text: you can see the <b>\e old online documentation</b>
of FLTK 1.3 at \b http://www.fltk.org/doc-1.3/toc.html
see section \ref development_non-ascii
\section development_old-links Changing Old Links
Old HTML links and anchors in text documentation pages should be changed
as follows:
\code
<H2><A name="event_xxx">Fl::event_*() methods</A></H2>
becomes:
<A NAME="event_xxx"></A> <!-- For old HTML links only ! -->
\section events_event_xxx Fl::event_*() methods
\endcode
The additional HTML "<A NAME=...>" statement is temporary needed, until
all links (references) are modified, then:
\code
<H2><A name="event_xxx">Fl::event_*() methods</A></H2>
becomes:
\section events_event_xxx Fl::event_*() methods
\endcode
The "\section" statement can also be a "\subsection" or "\subsubsection"
statement.
The references (in this example from index.dox) are changed as follows:
\code
\subpage events
<B>
<UL>
<LI><A HREF="events.html#event_xxx">Fl::event_*() methods</A></LI>
<LI><A HREF="events.html#propagation">Event Propagation</A></LI>
</UL>
</B>
becomes:
\subpage events
<b>
\li \ref events_event_xxx
\li \ref events_propagation
</b>
\endcode
\section development_html_footer Hack for missing "tiny.gif" file
\todo
*HACK* : include image file for footer. Doxygen does not include
the file "tiny.gif" from "html_footer" in its output html dir.
Find out, how this can be done, or avoid using an image in
the HTML footer.
\image html tiny.gif
\section development_navigation_test 5 Navigation Proposals
<hr>
\link migration_1_3 [ Previous ] \endlink
<b> [ <a href="index.html">Index</a> ] </b>
<b> Next: </b> \ref license
<hr>
<b>[ <a href="index.html">Index</a> ] </b>
<b> Previous: </b> \ref migration_1_3
<b> Next: </b> \ref license
<hr>
<b>[ <a href="index.html">Index</a> ] </b><br>
<b> Previous: </b> \ref migration_1_3 <br>
<b> Next: </b> \ref license
<hr>
<b>[ <a href="index.html">Index</a> ] </b>
Previous: \ref migration_1_3
Next: \ref license
<hr>
\link migration_1_3 [ Previous ] \endlink
<b> [ <a href="index.html">Top</a> ] </b>
\link license [ Next ] \endlink
<hr>
<br>
<br>
\section development_proposed_nav Proposed (final) Navigation Elements
See below.
<hr>
<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
<a class="el" href="migration_1_3.html">[Previous]</a>&nbsp;
\ref migration_1_3 &nbsp;&nbsp;
<a class="el" href="license.html">[Next]</a>&nbsp;
\ref license
*/