Author: matt Date: 2010-03-13 08:21:52 -0800 (Sat, 13 Mar 2010) New Revision: 7253 Log: 123: moving docs into its own directory
Added: branches/branch-3.0-matt/123/ branches/branch-3.0-matt/123/README.txt Copied: branches/branch-3.0-matt/123/README.txt (from rev 7251, branches/branch-3.0-matt/README.123) =================================================================== --- branches/branch-3.0-matt/123/README.txt (rev 0) +++ branches/branch-3.0-matt/123/README.txt 2010-03-13 16:21:52 UTC (rev 7253) @@ -0,0 +1,703 @@ + + R E A D M E . 1 2 3 + ===================== + +This file listst the differences between FLTK 1 and FLTK 2 with annotations +for a possible implementation of FLTK 3. The all new and improved FLTK 3 +needs to be compatible with 1 and 2. It must have a modern API, a complete set of +widgets, lots of options, customization at run-time, but still be easily +portable, fast, and, of course, light. + +FLTK 1 has evolved to be a great starting point for the first steps in GUI +programming. It runs on all major platform (and on many minor ones +as well), is small, compact, and easy to use. FLTK 2 was the +attempt to continue the success of FLTK 1 with a clearer and more modern API +and many important details improved. Unfortunately many users never +made the jump to FLTK 2 and so it not only ended in a crawling slow +branch, it also became instable and at last unmaintainable. + +FLTK 3 sets out to surprise FLTK 1 users and satisfy FLTK 2 junkies. +It will basically be the improved FLTK 2 API combined with the proven and +stable innards of FLTK 1. As an extra bonus, FLTK 3 will be compatible +to 1 and 2. Just prepend your code with the "coding_style" instruction +and FLTK 3 will do the rest. It is even possible to intermix F1 and +F2 coding styles at any place. + +Nice challange, eh? So let's get going: + + + The Big Differences +--------------------- + +FLTK 2 is based on FLTK 1 in many ways, and while the FLTK 1 API was based +on the Forms Library, FLTK 2 is Bill's take on how FLTK 1 should have been. +This chapter outlines the biggest differences between version. + +(1) Coordinate System: FLTK 1 child coordinates are always relative to the +window, not as most would expect to the parent group. FLTK 2 does the logical +thing and uses group-relative origins. This is somewhat difficult to port +if we want to stay downward compatible. Fl_Widget will need an additional +flag indicating absolute or relative coordinates. + +(2) Pulldown Menus: The developers of the Forms Library did not implement +the idea of hierarchies all the way through. Pulldown menus, which are +hierarchical by nature, were instead implemented as a list with lots of +tricks and kludges to make them usable. FLTK 2 went half way by using the +existing Windget/Group relation to create menus, however, menu items are +still specialized widgets. For FLTK 3, I would like to allow any widget +inside a pulldown menu, using the hierarchical nature of the FLTK base class Fl_Widget. + +(3) Browsers and Tree Views: Browsers in FLTK1 are implemented even worse +than Pulldown Menus. FLTK 2 solved the issues in a similar way, and here +again, I prefer the FLTK 2 way very mch, but also would like to extend +functionality to allow arbitrary widgets as list items. A Tree-like +widget comes free with the FLTK 2 concept. FLTK 1 has no such thing and +even Fluid had to hack the library badly to generate a tree view. +FLTK 1.3 now comes with Greg's Fl_Tree widget. + +(4) Namespaces: this is a minr issue that I include for completeness. FLTK 2 +introduces the fltk namespace, renaming all widgets. FLTK 3 will use the +FLTK 2 naming scheme and map FLTK 1 class names using typedefs. This is, as +most things in programming are, a compromise. The "coding_style" function +must be used to switch between FLTK 1 and FLTK 2 code. No worries though, +it's easy and straight forward. + +(5) Layout: FLTK 1 uses a top-down approach for widget layout in which the +parent widget decides about the child's size "resize(x, y, w, h)". In FLTK 2 +any widget can call "layout()" which will query children for their preferred +size and propagate the information up. This is a great concept that FLTK 3 +should adapt, plus it is compatible. + +(6) Rectangle: FLTK uses discrete coordinates and sizes. FLTK 2's base class is fltk::Rectangle. This is nice and +easy to implement. The API is pretty much the same in both versions. + +(7) Styles: FLTK 2 uses a minimal number of styles to define the basic +(and often repeated) parameters of every widget. API's are similar though, +so this is luckily another pretty straight-forward upgrade. + + + Comparison Chart by Class +--------------------------- + +This chart contains a list of all classes in FLTK 1 and 2, how they +correspond, and how they could be implemented in FLTK 3. + +1: class Fl +2: namespace fltk +*: this is a pretty straight-forward mapping of functions. The actual work + lies in finding and listing all global functions and adapting those. + +1: class Fl_Adjuster +2: class Adjuster +*: should map easily + +1: +2: class AlignGroup +*: undocumented in FLTK 2. Minimal code. Can be transfered easily. + +1: +2: class AnsiWidget +*: There is no equvalet in FLTK 1, but the widget may be easily ported. + +1: +2: class AssociationFunctor +*: Associations are a new and rarly used concept in FLTK 2. We need to + decide if these should be moved into FLTK 3 + +1: +2: class AssociationType +*: Associations are a new and rarly used concept in FLTK 2. We need to + decide if these should be moved into FLTK 3 + +1: +2: class BarGroup +*: undocumented in FLTK 2. Minimal code. Can be transfered easily. + +1: class Fl_BMP_Image +2: class bmpImage +*: should map easily + +1: class Fl_Bitmap +2: + +1: class Fl_Box +2: class Widget +*: This actually maps pretty much exactly to fltk::Widget. FLTK 2 provides + a bunch of other box-like classes which have some predefined properties, + however this is the best match for FLTK 1. fltk::InvisibleBox can be used + as well. + +1: class Fl_Browser +2: class Browser + +1: class Fl_Browser_ +2: + +1: class Fl_Button +2: class Button +*: should map easily + +1: class Fl_Cairo_State +2: + +1: class Fl_Cairo_Window +2: + +1: class Fl_Chart +2: + +1: class Fl_Check_Browser +2: + +1: class Fl_Check_Button +2: class CheckButton +*: should map easily + +1: class Fl_Choice +2: class Choice +*: should map easily + +1: class Fl_Clock +2: class Clock +*: should map easily + +1: class Fl_Clock_Output +2: class ClockOutput +*: should map easily + +1: class Fl_Color_Chooser +2: class ColorChooser +*: should map easily + +1: +2: class ComboBrowser + +1: +2: class ComboWindow + +1: +2: class CycleButton + +1: class Fl_Counter +2: + +1: class Fl_Dial +2: class Dial +*: should map easily + +1: class Fl_Box +2: class Divider +*: + +1: class Fl_Double_Window +2: class DoubleBufferWindow +*: should map easily + +1: class Fl_End +2: + +1: Fl_Box +2: class EngravedLabel + +1: class Fl_File_Browser +2: class FileBrowser +*: should map easily + +1: class Fl_File_Chooser +2: class FileChooser +*: should map easily + +1: class Fl_File_Icon +2: class FileIcon +*: should map easily + +1: class Fl_File_Input +2: class FileInput +*: should map easily + +1: class Fl_Fill_Dial +2: class FillDial +*: should map easily + +1: class Fl_Fill_Slider +2: class FillSlider +*: should map easily + +1: +2: class FlatBox + +1: class Fl_Float_Input +2: class FloatInput +*: should map easily + +1: class Fl_FormsBitmap +2: + +1: class Fl_FormsPixmap +2: + +1: class Fl_FormsText +2: class Fl_FormsText +*: should map easily + +1: +2: class FrameBox + +1: class Fl_Free +2: + +1: class Fl_GIF_Image +2: class gifImage +*: should map easily + +1: class Fl_Gl_Choice +2: class GlChoice +*: should map easily + +1: class Fl_Gl_Window +2: class GlWindow +*: should map easily + +1: +2: class GlOverlay + +1: class Fl_Glut_Window +2: class GlutWindow + +1: class Fl_Group +2: class Group +*: should map easily, must manage coordinate systems + +1: +2: class GSave + +1: +2: class Guard + +1: class Fl_Help_Dialog +2: class HelpDialog +*: should map easily + +1: class Fl_Help_View +2: class HelpView +*: should map easily + +1: +2: class HighlightBox + +1: +2: class HighlightButton + +1: class Fl_Hold_Browser +2: + +1: class Fl_Hor_Fill_Slider +2: + +1: class Fl_Hor_Nice_Slider +2: + +1: class Fl_Hor_Slider +2: + +1: class Fl_Hor_Value_Slider +2: + +1: class Fl_Image +2: class Image +*: should map easily + +1: class Fl_Input +2: class Input +*: should map easily + +1: class Fl_Input_ +2: + +1: +2: class InputBrowser + +1: class Fl_Input_Choice +2: class ComboBox +*: should map easily + +1: class Fl_Int_Input +2: class IntInput +*: should map easily + +1: +2: class InvisibleBox + +1: struct Fl_Menu_Item +2: class Item +*: this will be hard to emulate! + +1: +2: class ItemGroup + +1: class Fl_JPEG_Image +2: class jpegImage +*: should map easily + +1: +2: class LabelType + +1: class Fl_Light_Button +2: class LightButton +*: should map easily + +1: class Fl_Line_Dial +2: class LineDial +*: should map easily + +1: +2: class List + +1: class Fl_Menu_ +2: class Menu + +1: class Fl_Menu_Bar +2: class MenuBar + +1: class Fl_Menu_Button +2: class PopupMenu + +1: +2: class MenuSection + +1: class Fl_Menu_Window +2: class MenuWindow + +1: class Fl_Screen? +2: class Monitor + +1: class Fl_Multi_Browser +2: class MultiBrowser + +1: +2: class MultiImage + +1: class Fl_Multiline_Input +2: class MultiLineInput +*: should map easily + +1: class Fl_Multiline_Output +2: class MultiLineOutput +*: should map easily + +1: Fl::lock() +2: class Mutex + +1: class Fl_Nice_Slider +2: + +1: +2: class NumericInput + +1: class Fl_Output +2: class Output +*: should map easily + +1: class Fl_Overlay_Window +2: + +1: class Fl_PNG_Image +2: class pngImage +*: should map easily + +1: class Fl_PNM_Image +2: class pnmImage +*: should map easily + +1: class Fl_Pack +2: class PackedGroup +*: should map easily, FLTK 2 has some additional functionaity + +1: class Fl_Pixmap +2: + +1: class Fl_Positioner +2: + +1: class Fl_Preferences +2: class Preferences +*: should map easily + +1: class Fl_Progress +2: class ProgressBar +*: should map easily + +1: class Fl_RGB_Image +2: class rgbImage +*: should map easily + +1: class Fl_Radio_Button +2: class RadioButton +*: should map easily + +1: +2: class RadioItem + +1: class Fl_Radio_Light_Button +2: class RadioLightButton +*: should map easily + +1: class Fl_Radio_Round_Button +2: + +1: +2: class Rectangle + +1: +2: class RecursiveMutex + +1: class Fl_Repeat_Button +2: class RepeatButton +*: should map easily + +1: class Fl_Return_Button +2: class ReturnButton +*: should map easily + +1: class Fl_Roller +2: class ThumbWheel +*: should map easily + +1: class Fl_Round_Button +2: + +1: class Fl_Round_Clock +2: + +1: class Fl_Scroll +2: class ScrollGroup +*: should map easily + +1: class Fl_Scrollbar +2: class Scrollbar +*: should map easily + +1: class Fl_Secret_Input +2: class SecretInput +*: should map easily + +1: class Fl_Select_Browser +2: + +1: +2: class ShapedWindow + +1: class Fl_Shared_Image +2: class SharedImage +*: should map easily + +1: +2: class ShortcutFunctor + +1: class Fl_Simple_Counter +2: + +1: class Fl_Single_Window +2: + +1: +2: class SignalMutex + +1: class Fl_Slider +2: class Slider +*: should map easily + +1: class Fl_Spinner +2: + +1: +2: class StatusBarGroup + +1: +2: class StringArray + +1: +2: class StringHierarchy + +1: +2: class StringList + +1: +2: class Style + +1: +2: class StyleSet + +1: +2: class Symbol + +1: class Fl_Sys_Menu_Bar +2: class SystemMenuBar +*: should map easily + +1: class Fl_Tabs +2: class TabGroup +*: should map easily + +1: +2: class TabGroupPager + +1: class Fl_Text_Buffer +2: class TextBuffer +*: should map easily + +1: class Fl_Text_Display +2: class TextDisplay +*: should map easily + +1: class Fl_Text_Editor +2: class TextEditor +*: should map easily + +1: class Fl_Text_Selection +2: class TextSelection +*: should map easily + +1: class Fl_Tile +2: class TiledGroup +*: should map easily + +1: class Fl_Tiled_Image +2: class TiledImage +*: should map easily + +1: class Fl_Timer +2: + +1: class Fl_Toggle_Button +2: class ToggleButton +*: should map easily + +1: +2: class ToggleItem + +1: class Fl_Tooltip +2: class Tooltip +*: should map easily + +1: +2: class WordwrapInput + +1: +2: class WordwrapOutput + +1: class Fl_Valuator +2: class Valuator +*: should map easily + +1: class Fl_Value_Input +2: class ValueInput +*: should map easily + +1: class Fl_Value_Output +2: class ValueOutput +*: should map easily + +1: class Fl_Value_Slider +2: class ValueSlider +*: should map easily + +1: class Fl_Widget +2: class Widget +*: should map easily for the most part + +1: class Fl_Widget_Tracker +2: + +1: class Fl_Window +2: class Window +*: should map easily + +1: class Fl_Wizard +2: class WizardGroup +*: should map easily + +1: class Fl_X +2: class CreatedWindow +*: should map easily + +1: class Fl_XBM_Image +2: class xbmImage +*: should map easily + +1: class Fl_XPM_Image +2: class xpmImage +*: should map easily + +1: +2: class xpmFileImage + +1: +2: struct Cursor + +1: +2: struct Font + +1: struct Fl_Glut_Bitmap_Font +2: + +1: struct Fl_Glut_StrokeChar +2: + +1: struct Fl_Glut_StrokeFont +2: + +1: struct Fl_Glut_StrokeStrip +2: + +1: struct Fl_Glut_StrokeVertex +2: + +1: struct Fl_Help_Block +2: struct HelpBlock +*: should map easily + +1: struct Fl_Help_Font_Stack +2: + +1: struct Fl_Help_Font_Style +2: + +1: struct Fl_Help_Link +2: struct HelpLink +*: should map easily + +1: struct Fl_Help_Target +2: struct HelpTarget +*: should map easily + +1: +2: struct ImageType + +1: struct Fl_Label +2: + +1: struct Fl_Menu_Item +2: + +1: struct Fl_Multi_Label +2: + +1: +2: struct NamedStyle + + + CONVERTING A CLASS + +- find the matchin headers +- copy the FLTK1 header to fltk3 +- append the same header agin +- append the fltk2 header +- fix the #ifdef's +- put the main class into the new namespace and rename the class +- write a new stub that is derived from the class above with the old class name +- fix constructor and destructor +- fix the class part of all method implementations +- do *not* change any parameters, variable types, or return types yet +- compile. Wherever there is an illegal conversion error, simply insert a cast for now + _______________________________________________ fltk-commit mailing list [email protected] http://lists.easysw.com/mailman/listinfo/fltk-commit
