diff options
Diffstat (limited to 'documentation/src/development.dox')
| -rw-r--r-- | documentation/src/development.dox | 462 |
1 files changed, 0 insertions, 462 deletions
diff --git a/documentation/src/development.dox b/documentation/src/development.dox deleted file mode 100644 index 616619c88..000000000 --- a/documentation/src/development.dox +++ /dev/null @@ -1,462 +0,0 @@ -/** - - \page development I - 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.gif - \image latex clock.eps "" width=10cm - \image html round_clock.gif - \image latex clock.eps "" width=10cm - \image html round_clock.eps "" 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 - \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_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_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 - \image latex tiny.eps "" width=2cm - -\section development_navigation_test 5 Navigation Proposals - -\htmlonly -<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> -<a class="el" href="migration_1_3.html">[Previous]</a> - \ref migration_1_3 -<a class="el" href="license.html">[Next]</a> - \ref license - -\endhtmlonly -*/ |