FLTK::Notes - Annotated Guide to the Ins and Outs of FLTK
I am actively seeking volunteers to help test and develop this project. Please see the notes on joining the team.
This is a first draft attempt at defining a road map for future development and a behavioral reference for users and third-party developers.
Right off the bat, here's a list of some of the important links refered to in this document.
Eventually, the official website will be http://sanko.github.com/perl-fltk/. There you'll find html versions of all the documentation, examples, the development blog, and links to other resources.
...eventually.
Eventually, the official means of support for FLTK may be through #fltk on... some IRC network. Probably Freenode. If anyone aside from me decides to show up on a regular basis.
#fltk
Yeah, ...eventually.
Follow the project on github: http://github.com/sanko/perl-fltk/
I'd need someone to host it. :\
Use http://github.com/sanko/perl-fltk/issues/list for bug tracking. Please include as much information as possible and review the list in the Bug Tracking section below.
I announce stable builds and occasionally complain on Twitter: http://twitter.com/FLTKpm
[TODO]
Please see the section on API Backward Compatibility.
See also the section on APIDoc.
For the most part, I have tried to emulate the official interface to FLTK but there are a few areas where I stray (sometimes drastically) from the C++ API Here, I'll list them and (for some) try to explain why.
If a change I mention here chafes you the wrong way, you're free to (within reason) bug me about it until I reconsider. ...and, in turn, I am free to ignore you if I'm busy or just about any other reason. Drop such requests in the issue tracker.
choice(...)'s choices (<_<) are shown in the correct order; from left to right.
choice(...)
Support for args(...), arg(...), and show(...)
args(...), arg(...), and show(...)
The latter two are used extensively in the tests that come with fltk but I don't think they're powerful enough to use in Perl. I would suggest using GetOpt::Long or another command line parser and then setting the values in FLTK manually.
I'm still thinking about this choice, so don't get too angry if your life is incomplete without arg(0, '-geometry blah', 0) support.
arg(0, '-geometry blah', 0)
FLTK::ask functions do not do sprintf-like stuff.
Working around XSUB's inability to take true variable argument lists isn't worth the time nor effort.
Anti-perl-isms
The Fast Light Toolkit's API is so C++ oriented that it makes me itch. Here, I'll list the places where things moved too far from what one might expect in a Perl module and I made a decision which strayes from the underlying C++ API.
FLTK::parsecolor ( COLOR, [ LENGTH ] )
The C++ function takes two parameters: parsecolor( char * name, unsigned length ) ...but this is Perl and forcing you to call parsecolor( $mycolor, length($mycolor) ) is silly.
parsecolor( char * name, unsigned length )
parsecolor( $mycolor, length($mycolor) )
FLTK::Browser::column_widths(), FLTK::Browser::current_index FLTK::Browser::focus_index FLTK::Browser::column_labels do not require a trailing zero (0) and do not add one to return values.
FLTK::Browser::column_widths()
FLTK::Browser::current_index
FLTK::Browser::focus_index
FLTK::Browser::column_labels
0
FLTK::addvertices and FLTK::addvertices_transformed don't require an initial total.
FLTK::addvertices
FLTK::addvertices_transformed
rgb2hsv($r, $g, $b) returns $h, $s, $v as opposed the C function which is defined as void rgb2hsv(r,b,g,h,s,v) and changes h, s, v in place.
rgb2hsv($r, $g, $b)
$h, $s, $v
void rgb2hsv(r,b,g,h,s,v)
h, s, v
hsv2rgb($h, $s, $v) returns $r, $b, $g as opposed the C function which is defined as void hsv2rbg(h, s, v, r, b, g) and changes r, b, g in place.
hsv2rgb($h, $s, $v)
$r, $b, $g
void hsv2rbg(h, s, v, r, b, g)
r, b, g
FLTK::Group->add( ... ), FLTK::Group->insert( ... ), and FLTK::Group->replace( ... ), return the widget added, inserted, or used as a replacement as of 0.532006_002
FLTK::Group->add( ... )
FLTK::Group->insert( ... )
FLTK::Group->replace( ... )
0.532006_002
If you work with any other setups (VC++, CygFail, etc.) and would like to lend a hand with development please join the team. If you just want to report a bug or help test, that's cool too.
FLTK requires Alien::FLTK2 (which attempts to build and install a local copy of the fltk libs) is listed as prerequisite in Build.PL so, unless you answer 'no' when prompted, the CPAN shell should automatically install it for you.
Build.PL
Other requirements are listed by system below.
This is a partial (and currently incomplete) list of OSs/setups known to work or have problems with FLTK. Where possible, workarounds are mentioned.
Absolutly untested. The fltk libs work on MacOS but the last time I had access to an Apple was in 1st grade. I played Number Munchers.
Before most major changes are uploaded, I run the test suite with the latest Xbuntu (LTS). Assistance (even if only test reports) from BSDs are welcome.
My primary dev environment is XP Professional with MinGW. If you work with any other setups (VC++, CygFail, etc.) and would like to lend a hand with development and/or testing, please join the team.
This distribution uses Module::Build for installation, so use the following procedure:
Module::Build
perl Build.PL ./Build ./Build test ./Build install
See also: Distribution Testing
Please refer to Alien::FLTK2.
This section lists recent major changes in API or behavior between stable releases. For older news see the Changes file included with this distribution. For detail see the commit logs.
...and yeah, I know this isn't fluff but it may grow too large to put near the top with API.
To make life easy, FLTK's documentation is in the xs source files near to whatever is being described. The documentation format is based on the apidoc found in perl's own core. ...why not steal a great idea, amirite?
During the build process, the documentation is pulled from the xs and .pod files are created and installed with the module.
For folks with an itch to hack or a flair for words and want to help improve the documentation, lines are of the form:
flags|prereq|return_type|function_name|arg1|arg2|...|argN flags are single letters with following meanings: D depreciated code/widget E enum/flag F function rather than an OO method* x experimental and may be removed or changed in a future version T[X,Y] exported by tags :X and :Y N basic functionality has changed since the last major release* U suppress usage example in auto-generated documentation H this is a hidden, internal (hacker only) function A interface or functionality differs from the original API prereq are single letters with the following meanings: G requires GL X requires the X Window system t requires pthreads (or Windows)* W requires Windows
* denotes stuff I haven't really given enough thought to and probably haven't used yet.
This format is subject to change.
This section describes all the behind the scenes stuff that makes FLTK work. Or not work. It depends. If you're interested in assisting with FLTK's development but don't know where to begin, here are a few ideas.
Also see the section on testing development builds.
...well, it's currently a team of one. But I'm looking for help. Skip down to the join the team section below.
FLTK is too large for just one person to hack on. If you're XS, C++, or just Perl-adept and would like to help, you can start by forking the project on github: http://github.com/sanko/perl-fltk/. When ready, send me a pull request, I'll look over your changes and get back to you. Minor patches get your name in the changelog. Really major contributions get your name in the Acknowledgments section and an invitation to be a trusted collaborator. Oooo. Ahhh.
FLTK
As "The Team" grows (assuming anyone helps me out...) the development cycle will grow with it. For now, a trimmed down version of Moose's contribution notes.
Found bugs should be reported through FLTK's Issue Tracker. Before creating a new report, please review the following list:
More than just about anything else, FLTK needs to be tested. Here are a couple ways you can help with that.
Becoming a CPAN Tester is an easy, automatic way to contribute to the quality of your favorite module and CPAN in general. If you would like to contribute automated test reports for FLTK, install CPAN::Reporter from the CPAN shell first:
CPAN::Reporter
$ cpan cpan> install CPAN::Reporter cpan> reload cpan cpan> o conf init test_report [...follow the CPAN::Reporter setup prompts...] cpan> o conf commit cpan> install FLTK
For more on becoming a CPAN Tester and why this is useful, see the CPAN::Reporter documentation and http://cpantesters.org/.
http://fltk.org/articles.php?L825+I0+T+P1+Q
Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/
CPAN ID: SANKO
Copyright (C) 2008-2009 by Sanko Robinson <sanko@cpan.org>
This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or http://www.perlfoundation.org/artistic_license_2_0. For clarification, see http://www.perlfoundation.org/artistic_2_0_notes.
When separated from the distribution, all POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See http://creativecommons.org/licenses/by-sa/3.0/us/legalcode. For clarification, see http://creativecommons.org/licenses/by-sa/3.0/us/.
To install FLTK, copy and paste the appropriate command in to your terminal.
cpanm
cpanm FLTK
CPAN shell
perl -MCPAN -e shell install FLTK
For more information on module installation, please visit the detailed CPAN module installation guide.