-
Notifications
You must be signed in to change notification settings - Fork 1
/
README_fltk1_to_fltk2.txt
191 lines (161 loc) · 7.27 KB
/
README_fltk1_to_fltk2.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
=======================================================
Minimum Survival Guide for porting FLTK1 apps to FLTK2
=======================================================
F. Costantini Version 0.3
===
ToC
===
I. FLTK2 Source Organisation
1. fltk include directory
2. fltk include filenames
3. fltk2 namespaces and naming conventions
II. FLTK2 Window creation and event loops
1. Group/Window creation / parenting differences
2. Window visibility
III. Popular fltk Widgets differences in instanciation and use
1. Button symbols handling
2. Boxes
3. Browser
4. Tabs
IV. FLTK2 events
1. Keyboard events
=====
Intro
=====
This little guide will help you to port existing fltk1 apps
to fltk2. Please note that though most of this content should
not change dramatically when will come the time of release version,
it is possible that it will slightly change as fltk2 is still
in development phase.
This guide is not intended to be exhaustive, but should
answer most common porting situations.
==================================
I. FLTK2 Source Organisation
==================================
1. fltk include directory
FL/*.H -> fltk/*.h
fltk1 (minimal) compatibility includes:
fltk/compat/FL/*.H
2. fltk include filenames
a. fltk2 header all have a lowercase .h extension
b. No fltk2 header should have a Fl_ prefix,
if you find the case please report it
c. FL/Fl.H equivalent include is now fltk/run.h
3. fltk2 namespaces and naming conventions
a. all fltk widgets and most public functions
are defined in the fltk namespace (without the Fl_ prefix).
For instance, creating a fltk2 Window could be written as follow:
fltk::Window myWin(300,300);
Or
you can use the C++ statement :
using namespace fltk;
before referencing a fltk2 widget,then previous sample could be written:
Window myWin(300,300);
Note1:
don't use the using statement in include files !
Usually it's a good idea to reference the namespace
after the include files section.
Note2:
In some rare situations, you will have to remove ambiguity
as with XWindow based unix systems,
be careful i.e. when using Button and Window classes
they will be for sure ambiguous after the use of <fltk/x.h> include.
Also concerning fltk files naming :
all lib names + fltk tools named .*fltk.* are named .*fltk2.*
As an example fluid is called fluid2, fltk_config is called fltk2_config
and libfltk.a is named libfltk2.a
Finally, constant Naming follow similar rules:
to design a fltk2 Color (Fl_Color equivalent) constant:
remove the FL_ prefix and add fltk::
example: FL_BLUE -> fltk::BLUE
===============================================
II. FLTK2 Window creation and event loops
===============================================
1. Group/Window creation / parenting differences
When creating any fltk2 widget2 that inherits from the Group class,
be careful not to omit the method:
myGroupKind.begin();
This is automatically called in fltk1 in the constructor,
so in fltk1 you can omit it but for some reasons,
it have NOT been the case on FLTK2.
So to continue with our example let's add one button to our fltk2 window:
fltk::Window myWin(300,300);
myWin.begin(); // mandatory on fltk2 don't forget it !
fltk::Button myButton(100, 130, 80, 30, "&I love fltk2");
myWin.end();
2. Window visibility
In fltk2 the shown() method is different from fltk1,
to get similar effect on fltk2 you must use visible() instead of shown().
(Typically when you are polling window events and you wait in a loop that the user
hide/close the window.
An example of following our example is:
myWin.show();
while(myWin.visible()) fltk::wait();
For handling the main Window event loop,
you won't use this and would preferably simply use :
fltk::run();
==============================================================
III. Popular fltk Widgets differences in instanciation and use
==============================================================
1. Button symbols handling
In fltk2 you can also assign Symbols to your buttons but in different ways from fltk1:
A Symbol can be an Image or a predefined glyph. All Image classes derives from Symbol.
a. Assigning a Symbol to a button
fltk::Button myButton(100, 130, 80, 30, "&I love fltk2");
myButton.image(new xpmImage(folder_small)); // an xpm image to this button
A simple example of this is use of image() other default parameters:
myButton.image(default,disabled, belowmouse, pushedopen);
This will affect four different images :
a default one, an image when widget is inactive,
an image raising when you put mouse over the widget (hoover-like effect)
and a pushed(open for Browser trees) image to differentiate
when pushing a button or opening a Browser tree node.
Another (even more powerful) way to achieve event dependent images
is to use the MultiImage class.
This class permits you to handle more than 4 combinations
but requires a bit more work to instanciate.
see fltk doxygen doc for more details;
Hints & summary:
i. In fltk2 you can use BOTH text labels and images in the same widget
ii. In fltk2, you can use multiple symbols/images according to the event type.
iii. Well known Fl_Pixmap fltk1 class correspond to fltk2 xpmImage.
2. Boxes
In FLTK2, there is basically no need for an equivalent fltk1 Fl_Box class.
Instead, all Widget and derived classes can use and benefit from a box
drawing capability by simply using the box() method.
For more straightforward/simple use of boxes (especially for fltk1 users)
you may like the InvisibleBox class.
Here's an example of use :
fltk::InvisibleBox b (UP_BOX,0,0,50,50, "My descriptive label in my box");
This will create a up box with a label centered by default inside the box.
3. Browser
The Browser class in fltk2 is very different from the fltk1 Fl_Browser class.
In fltk2, it also permits to address most tree view needs, and multi-columning.
(fltk::Browser was first implemented from Marteen de Boer ToggleTree contrib.).
As Browser inherits from Menu,
in order to walk the fltk2 browser tree,
you 'll use the menu inherited methods like child(), children().
Be careful when indexing browser items, items start at index 0 in fltk2,
but 0 mean no item in fltk1.
Though the new fltk2 Browser is quite complex, it can be implemented quite easily
(see Browser demo for more details and doxygen documentation containing example of use )
Another hint to port complex browser use may be to have a look to
the fltk2 FileBrowser port from fltk1 and used in FileChooser in the fltk2 lib.
4. Tabs
fltk1 Fl_Tabs class is TabGroup class in fltk2.
In fltk1 value() get/set method use the Widget group pointer in order
to select a tab, fltk2 TabGroup is only asking for a relative position instead.
You can still obtain the Widget group pointing at this index easily
by using the standard child() method from the TabGroup
=======================
IV. FLTK2 events
=======================
1. Keyboard events
- Instead of calling Fl::event_key(), you 'll call fltk::event_key().
- Fltk1 keyboard enum also changes (fltk/events.h) so for example:
Left -> LeftKey, Right->RightKey, Enter -> ReturnKey, etc ...
2.
* TODO next :
font management differences
image management differences (what a pain)
drawing api differences / similitudes