1/** 2 <!-- Warning: \p .fl does not work but <tt>.fl</tt> does --> 3 <!-- Warning: \p .h does not work but <tt>.h</tt> does --> 4 <!-- Warning: \p .cxx does not work but <tt>.cxx</tt> does --> 5 6 \page fluid Programming with FLUID 7 8This chapter shows how to use the Fast Light User-Interface Designer 9("FLUID") to create your GUIs. 10 11Subchapters: 12 13\li \ref fluid_what_is_fluid 14\li \ref fluid_fluid_under_unix 15\li \ref fluid_fluid_under_windows 16\li \ref fluid_compiling_fl_files 17\li \ref fluid_tutorial 18\li \ref fluid_references 19\li \ref fluid_i18n 20\li \ref fluid_limitations 21 22\section fluid_what_is_fluid What is FLUID? 23 24The Fast Light User Interface Designer, or FLUID, is a 25graphical editor that is used to produce FLTK source code. FLUID 26edits and saves its state in <tt>.fl</tt> files. These files 27are text, and you can (with care) edit them in a text editor, 28perhaps to get some special effects. 29 30FLUID can "compile" the <tt>.fl</tt> file into a 31<tt>.cxx</tt> and a <tt>.h</tt> file. The <tt>.cxx</tt> file 32defines all the objects from the <tt>.fl</tt> file and the 33<tt>.h</tt> file declares all the global ones. FLUID also 34supports localization (\ref fluid_i18n "Internationalization") 35of label strings using message files and the GNU gettext or 36POSIX catgets interfaces. 37 38A simple program can be made by putting all your code (including a 39\p main() function) into the <tt>.fl</tt> file and thus making the 40<tt>.cxx</tt> file a 41single source file to compile. Most programs are more complex than 42this, so you write other <tt>.cxx</tt> files that call the FLUID functions. 43These <tt>.cxx</tt> files must 44\p \#include 45the <tt>.h</tt> file or they can 46\p \#include 47the <tt>.cxx</tt> file so it still appears to be a single source file. 48 49 \image html fluid-org.png "Figure 9-1: FLUID organization" 50 \image latex fluid-org.png "FLUID organization" width=12cm 51 52Normally the FLUID file defines one or more functions or classes which 53output C++ code. Each function defines one or more FLTK 54windows, and all the widgets that go inside those windows. 55 56Widgets created by FLUID are either "named", "complex named" or 57"unnamed". A named widget has a legal C++ variable identifier as its 58name (i.e. only alphanumeric and underscore). In this case FLUID 59defines a global variable or class member that will point at the widget 60after the function defining it is called. A complex named object has 61punctuation such as <tt>'.'</tt> or <tt>'->'</tt> or any other symbols 62in its name. In 63this case FLUID assigns a pointer to the widget to the name, but does 64not attempt to declare it. This can be used to get the widgets into 65structures. An unnamed widget has a blank name and no pointer is stored. 66 67Widgets may either call a named callback function that you write in 68another source file, or you can supply a small piece of C++ source and 69FLUID will write a private callback function into the <tt>.cxx</tt> file. 70 71\section fluid_fluid_under_unix Running FLUID Under UNIX 72 73To run FLUID under UNIX, type: 74 75\code 76fluid filename.fl & 77\endcode 78 79to edit the <tt>.fl</tt> file <tt>filename.fl</tt>. 80If the file does not exist 81you will get an error pop-up, but if you dismiss it you will be editing 82a blank file of that name. You can run FLUID without any name, in 83which case you will be editing an unnamed blank setup (but you can use 84save-as to write it to a file). 85 86You can provide any of the standard FLTK switches before the filename: 87 88\code 89-display host:n.n 90-geometry WxH+X+Y 91-title windowtitle 92-name classname 93-iconic 94-fg color 95-bg color 96-bg2 color 97-scheme schemename 98\endcode 99 100Changing the colors may be useful to see what your interface 101will look at if the user calls it with the same switches. 102Similarly, using "-scheme plastic" will show how the interface 103will look using the "plastic" scheme. 104 105In the current version, if you don't put FLUID into the 106background with <tt>'&'</tt> then you will be able to abort FLUID by 107typing <tt>CTRL-C</tt> on the terminal. It will exit 108immediately, losing any changes. 109 110\section fluid_fluid_under_windows Running FLUID Under Microsoft Windows 111 112To run FLUID under WIN32, double-click on the \e FLUID.exe 113file. You can also run FLUID from the Command Prompt window. 114FLUID always runs in the background under WIN32. 115 116\section fluid_compiling_fl_files Compiling .fl files 117 118FLUID can also be called as a command-line 119"compiler" to create the <tt>.cxx</tt> and <tt>.h</tt> 120file from a <tt>.fl</tt> file. To do this type: 121 122\code 123fluid -c filename.fl 124\endcode 125 126This is the same as the menu 'File/Write Code...'. 127It will read the <tt>filename.fl</tt> file and write 128<tt>filename.cxx</tt> and <tt>filename.h</tt>. Any leading 129directory on <tt>filename.fl</tt> will be stripped, so they are 130always written to the current directory. If there are any errors 131reading or writing the files, FLUID will print the error and 132exit with a non-zero code. You can use the following lines in a 133makefile to automate the creation of the source and header 134files: 135 136\code 137my_panels.h my_panels.cxx: my_panels.fl 138 fluid -c my_panels.fl 139\endcode 140 141Most versions of make support rules that cause <tt>.fl</tt> 142files to be compiled: 143 144\code 145.SUFFIXES: .fl .cxx .h 146.fl.h .fl.cxx: 147 fluid -c $< 148\endcode 149 150If you use 151 152\code 153fluid -cs filename.fl 154\endcode 155 156FLUID will also write the "strings" for internationalization in file 157'filename.txt' (menu: 'File/Write Strings...'). 158 159Finally there is another option which is useful for program developers 160who have many .fl files and want to upgrade them to the current FLUID 161version. FLUID will read the \p filename.fl file, save it, and exit 162immediately. This writes the file with current syntax and options and 163the current FLTK version in the header of the file. Use 164 165\code 166fluid -u filename.fl 167\endcode 168 169to 'upgrade' \p filename.fl . You may combine this with '-c' or '-cs'. 170 171\note All these commands overwrite existing files w/o warning. You should 172particularly take care when running 'fluid -u' since this overwrites the 173original .fl source file. 174 175 176\section fluid_tutorial A Short Tutorial 177 178FLUID is an amazingly powerful little program. However, this 179power comes at a price as it is not always obvious how to 180accomplish seemingly simple tasks with it. This tutorial will 181show you how to generate a complete user interface class with 182FLUID that is used for the CubeView program provided with FLTK. 183 184\image html cubeview.png "Figure 9-2: CubeView demo" 185\image latex cubeview.png "CubeView demo" width=10cm 186 187The window is of class CubeViewUI, and is completely generated by FLUID, 188including 189class member functions. The central display of the cube is a separate 190subclass of Fl_Gl_Window called CubeView. CubeViewUI manages CubeView 191using callbacks from the various sliders and rollers to manipulate the 192viewing angle and zoom of CubeView. 193 194At the completion of this tutorial you will (hopefully) understand 195how to: 196 197-# Use FLUID to create a complete user interface class, including 198 constructor and any member functions necessary. 199-# Use FLUID to set callbacks member functions of a custom widget 200 classes. 201-# Subclass an Fl_Gl_Window to suit your purposes. 202 203\subsection fluid_cubeview The CubeView Class 204 205The CubeView class is a subclass of Fl_Gl_Window. It has methods for 206setting the zoom, the \e x and \e y pan, and the rotation angle 207about the \e x and \e y axes. 208 209You can safely skip this section as long as you realize that CubeView 210is a sublass of Fl_Gl_Window and will respond to calls from 211CubeViewUI, generated by FLUID. 212 213\par The CubeView Class Definition 214 215Here is the CubeView class definition, as given by its header file 216"test/CubeView.h": 217 218\code 219class CubeView : public Fl_Gl_Window { 220 public: 221 CubeView(int x,int y,int w,int h,const char *l=0); 222 // this value determines the scaling factor used to draw the cube. 223 double size; 224 /* Set the rotation about the vertical (y ) axis. 225 * 226 * This function is called by the horizontal roller in CubeViewUI 227 * and the initialize button in CubeViewUI. 228 */ 229 void v_angle(float angle){vAng=angle;}; 230 // Return the rotation about the vertical (y ) axis. 231 float v_angle(){return vAng;}; 232 /* Set the rotation about the horizontal (x ) axis. 233 * 234 * This function is called by the vertical roller in CubeViewUI 235 and the 236 * initialize button in CubeViewUI. 237 */ 238 void h_angle(float angle){hAng=angle;}; 239 // the rotation about the horizontal (x ) axis. 240 float h_angle(){return hAng;}; 241 /* Sets the x shift of the cube view camera. 242 * 243 * This function is called by the slider in CubeViewUI and the 244 * initialize button in CubeViewUI. 245 */ 246 void panx(float x){xshift=x;}; 247 /* Sets the y shift of the cube view camera. 248 * 249 * This function is called by the slider in CubeViewUI and the 250 * initialize button in CubeViewUI. 251 */ 252 void pany(float y){yshift=y;}; 253 /* The widget class draw() override. 254 * The draw() function initialize Gl for another round of 255 * drawing then calls specialized functions for drawing each 256 * of the entities displayed in the cube view. 257 */ 258 void draw(); 259 260 private: 261 /* Draw the cube boundaries 262 * Draw the faces of the cube using the boxv[] vertices, using 263 * GL_LINE_LOOP for the faces. The color is #defined by 264 * CUBECOLOR. 265 */ 266 void drawCube(); 267 268 float vAng,hAng; float xshift,yshift; 269 270 float boxv0[3];float boxv1[3]; float boxv2[3];float boxv3[3]; 271 float boxv4[3];float boxv5[3]; float boxv6[3];float boxv7[3]; 272}; 273\endcode 274 275\par The CubeView Class Implementation 276 277Here is the CubeView implementation. It is very similar to the 278"cube" demo included with FLTK. 279 280\code 281#include "CubeView.h" 282#include <math.h> 283 284CubeView::CubeView(int x,int y,int w,int h,const char *l) 285 : Fl_Gl_Window(x,y,w,h,l) 286{ 287 vAng = 0.0; hAng=0.0; size=10.0; 288 /* The cube definition. These are the vertices of a unit cube 289 * centered on the origin.*/ 290 boxv0[0] = -0.5; boxv0[1] = -0.5; boxv0[2] = -0.5; boxv1[0] = 0.5; 291 boxv1[1] = -0.5; boxv1[2] = -0.5; boxv2[0] = 0.5; boxv2[1] = 0.5; 292 boxv2[2] = -0.5; boxv3[0] = -0.5; boxv3[1] = 0.5; boxv3[2] = -0.5; 293 boxv4[0] = -0.5; boxv4[1] = -0.5; boxv4[2] = 0.5; boxv5[0] = 0.5; 294 boxv5[1] = -0.5; boxv5[2] = 0.5; boxv6[0] = 0.5; boxv6[1] = 0.5; 295 boxv6[2] = 0.5; boxv7[0] = -0.5; boxv7[1] = 0.5; boxv7[2] = 0.5; 296}; 297 298// The color used for the edges of the bounding cube. 299#define CUBECOLOR 255,255,255,255 300 301void CubeView::drawCube() { 302/* Draw a colored cube */ 303#define ALPHA 0.5 304 glShadeModel(GL_FLAT); 305 306 glBegin(GL_QUADS); 307 glColor4f(0.0, 0.0, 1.0, ALPHA); 308 glVertex3fv(boxv0); 309 glVertex3fv(boxv1); 310 glVertex3fv(boxv2); 311 glVertex3fv(boxv3); 312 313 glColor4f(1.0, 1.0, 0.0, ALPHA); 314 glVertex3fv(boxv0); 315 glVertex3fv(boxv4); 316 glVertex3fv(boxv5); 317 glVertex3fv(boxv1); 318 319 glColor4f(0.0, 1.0, 1.0, ALPHA); 320 glVertex3fv(boxv2); 321 glVertex3fv(boxv6); 322 glVertex3fv(boxv7); 323 glVertex3fv(boxv3); 324 325 glColor4f(1.0, 0.0, 0.0, ALPHA); 326 glVertex3fv(boxv4); 327 glVertex3fv(boxv5); 328 glVertex3fv(boxv6); 329 glVertex3fv(boxv7); 330 331 glColor4f(1.0, 0.0, 1.0, ALPHA); 332 glVertex3fv(boxv0); 333 glVertex3fv(boxv3); 334 glVertex3fv(boxv7); 335 glVertex3fv(boxv4); 336 337 glColor4f(0.0, 1.0, 0.0, ALPHA); 338 glVertex3fv(boxv1); 339 glVertex3fv(boxv5); 340 glVertex3fv(boxv6); 341 glVertex3fv(boxv2); 342 glEnd(); 343 344 glColor3f(1.0, 1.0, 1.0); 345 glBegin(GL_LINES); 346 glVertex3fv(boxv0); 347 glVertex3fv(boxv1); 348 349 glVertex3fv(boxv1); 350 glVertex3fv(boxv2); 351 352 glVertex3fv(boxv2); 353 glVertex3fv(boxv3); 354 355 glVertex3fv(boxv3); 356 glVertex3fv(boxv0); 357 358 glVertex3fv(boxv4); 359 glVertex3fv(boxv5); 360 361 glVertex3fv(boxv5); 362 glVertex3fv(boxv6); 363 364 glVertex3fv(boxv6); 365 glVertex3fv(boxv7); 366 367 glVertex3fv(boxv7); 368 glVertex3fv(boxv4); 369 370 glVertex3fv(boxv0); 371 glVertex3fv(boxv4); 372 373 glVertex3fv(boxv1); 374 glVertex3fv(boxv5); 375 376 glVertex3fv(boxv2); 377 glVertex3fv(boxv6); 378 379 glVertex3fv(boxv3); 380 glVertex3fv(boxv7); 381 glEnd(); 382};//drawCube 383 384void CubeView::draw() { 385 if (!valid()) { 386 glLoadIdentity(); glViewport(0,0,w(),h()); 387 glOrtho(-10,10,-10,10,-20000,10000); glEnable(GL_BLEND); 388 glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA); 389 } 390 391 glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); 392 glPushMatrix(); glTranslatef(xshift, yshift, 0); 393 glRotatef(hAng,0,1,0); glRotatef(vAng,1,0,0); 394 glScalef(float(size),float(size),float(size)); drawCube(); 395 glPopMatrix(); 396}; 397\endcode 398 399\subsection fluid_cubevieui The CubeViewUI Class 400 401We will completely construct a window to display and control the 402CubeView defined in the previous section using FLUID. 403 404\par Defining the CubeViewUI Class 405 406Once you have started FLUID, the first step in defining a class is to 407create a new class within FLUID using the <b>New->Code->Class</b> 408menu item. Name the class "CubeViewUI" and leave the 409subclass blank. We do not need any inheritance for this 410window. You should see the new class declaration in the FLUID 411browser window. 412 413\image html fluid1.png "Figure 9-3: FLUID file for CubeView" 414\image latex fluid1.png "FLUID file for CubeView" width=10cm 415 416\par Adding the Class Constructor 417 418Click on the CubeViewUI class in the FLUID window and add a new method 419by selecting <b>New->Code->Function/Method.</b> The name of the 420function will also be CubeViewUI. FLUID will understand that this will 421be the constructor for the class and will generate the appropriate 422code. Make sure you declare the constructor public. 423 424Then add a window to the CubeViewUI class. Highlight the name of 425the constructor in the FLUID browser window and click on 426<b>New->Group->Window</b>. In a similar manner add the 427following to the CubeViewUI constructor: 428 429\li A horizontal roller named \p hrot 430\li A vertical roller named \p vrot 431\li A horizontal slider named \p xpan 432\li A vertical slider named \p ypan 433\li A horizontal value slider named \p zoom 434 435None of these additions need be public. And they shouldn't be 436unless you plan to expose them as part of the interface for 437CubeViewUI. 438 439When you are finished you should have something like this: 440 441\image html fluid2.png "Figure 9-4: FLUID window containing CubeView demo" 442\image latex fluid2.png "FLUID window containing CubeView demo" width=10cm 443 444We will talk about the \p show() method that is highlighted 445shortly. 446 447\par Adding the CubeView Widget 448 449What we have is nice, but does little to show our cube. We have already 450defined the CubeView class and we would like to show it within the 451CubeViewUI. 452 453The CubeView class inherits the Fl_Gl_Window class, which 454is created in the same way as a Fl_Box widget. Use 455<b>New->Other->Box</b> to add a square box to the main window. 456This will be no ordinary box, however. 457 458The Box properties window will appear. The key to letting CubeViewUI 459display CubeView is to enter CubeView in the <b>Class:</b> text 460entry box. This tells FLUID that it is not an Fl_Box, but a 461similar widget with the same constructor. 462 463In the <b>Extra Code:</b> field enter <tt>\#include "CubeView.h"</tt> 464 465This \p \#include is important, as we have just included 466CubeView as a member of CubeViewUI, so any public CubeView methods are 467now available to CubeViewUI. 468 469\image html fluid3-cxx.png "Figure 9-5: CubeView methods" 470\image latex fluid3-cxx.png "CubeView methods" width=10cm 471 472\par Defining the Callbacks 473 474Each of the widgets we defined before adding CubeView can have 475callbacks that call CubeView methods. You can call an external 476function or put in a short amount of code in the <b>Callback</b> 477field of the widget panel. For example, the callback for the 478\p ypan slider is: 479 480\code 481cube->pany(((Fl_Slider *)o)->value()); 482cube->redraw(); 483\endcode 484 485We call <tt>cube->redraw()</tt> after changing the value to update 486the CubeView window. CubeView could easily be modified to do this, but 487it is nice to keep this exposed. In the case where you may want to do 488more than one view change only redrawing once saves a lot of time. 489 490There is no reason to wait until after you have added CubeView to 491enter these callbacks. FLUID assumes you are smart enough not to refer 492to members or functions that don't exist. 493 494\par Adding a Class Method 495 496You can add class methods within FLUID that have nothing to do with the 497GUI. As an example add a show function so that CubeViewUI can actually 498appear on the screen. 499 500Make sure the top level CubeViewUI is selected and select 501<b>New->Code->Function/Method</b>. Just use the name 502\p show(). We don't need a return value here, and since we will 503not be adding any widgets to this method FLUID will assign it a return 504type of \p void. 505 506\image html fluid4.png "Figure 9-6: CubeView constructor" 507\image latex fluid4.png "CubeView constructor" width=10cm 508 509Once the new method has been added, highlight its name and select 510<b>New->Code->Code.</b> Enter the method's code in the code window. 511 512\subsection fluid_addconst Adding Constructor Initialization Code 513 514If you need to add code to initialize a class, for example setting 515initial values of the horizontal and vertical angles in the 516CubeView, you can simply highlight the constructor and select 517<b>New->Code->Code</b>. Add any required code. 518 519\subsection fluid_gencode Generating the Code 520 521Now that we have completely defined the CubeViewUI, we have to generate 522the code. There is one last trick to ensure this all works. Open the 523preferences dialog from <b>Edit->Preferences</b>. 524 525At the bottom of the preferences dialog box is the key: 526<b>"Include Header from Code"</b>. 527Select that option and set your desired file 528extensions and you are in business. You can include the CubeViewUI.h 529(or whatever extension you prefer) as you would any other C++ class. 530 531<!-- NEW PAGE --> 532 533\section fluid_references FLUID Reference 534 535The following sections describe each of the windows in FLUID. 536 537\subsection fluid_browser The Widget Browser 538 539The main window shows a menu bar and a scrolling browser of 540all the defined widgets. The name of the <tt>.fl</tt> file being 541edited is shown in the window title. 542 543The widgets are stored in a hierarchy. You can open and close a 544level by clicking the "triangle" at the left of a widget. 545The leftmost widgets are the \e parents, and all the widgets 546listed below them are their \e children. Parents don't have to have 547any children. 548 549The top level of the hierarchy is composed of \e functions and 550\e classes. Each of these will produce a single C++ public 551function or class in the output <tt>.cxx</tt> file. Calling the function or 552instantiating the class will create all of the child widgets. 553 554The second level of the hierarchy contains the \e windows. 555Each of these produces an instance of class Fl_Window. 556 557Below that are either \e widgets (subclasses of Fl_Widget) or 558\e groups of widgets (including other groups). Plain groups are for 559layout, navigation, and resize purposes. <i>Tab groups</i> provide the 560well-known file-card tab interface. 561 562Widgets are shown in the browser by either their \e name (such 563as "main_panel" in the example), or by their \e type 564and \e label (such as "Button "the green""). 565 566You \e select widgets by clicking on their names, which highlights 567them (you can also select widgets from any displayed window). You can 568select many widgets by dragging the mouse across them, or by using 569Shift+Click to toggle them on and off. To select no widgets, click in 570the blank area under the last widget. Note that hidden children may 571be selected even when there is no visual indication of this. 572 573You \e open widgets by double-clicking on them, or (to open several 574widgets you have picked) by typing the F1 key. A control panel will appear 575so you can change the widget(s). 576 577\subsection fluid_menu_items Menu Items 578 579The menu bar at the top is duplicated as a pop-up menu on any 580displayed window. The shortcuts for all the menu items work in any 581window. The menu items are: 582 583\par File/Open... (Ctrl+o) 584 585\par 586Discards the current editing session and reads in a different 587<tt>.fl</tt> file. You are asked for confirmation if you have 588changed the current file. 589 590\par 591FLUID can also read <tt>.fd</tt> files produced by the Forms 592and XForms "fdesign" programs. It is best to 593File/Merge them instead of opening them. FLUID does not 594understand everything in a <tt>.fd</tt> file, and will print a 595warning message on the controlling terminal for all data it does 596not understand. You will probably need to edit the resulting 597setup to fix these errors. Be careful not to save the file 598without changing the name, as FLUID will write over the 599<tt>.fd</tt> file with its own format, which fdesign cannot 600read! 601 602\par File/Insert... (Ctrl+i) 603 604\par 605Inserts the contents of another <tt>.fl</tt> file, without 606changing the name of the current <tt>.fl</tt> file. All the 607functions (even if they have the same names as the current ones) 608are added, and you will have to use cut/paste to put the widgets 609where you want. 610 611\par File/Save (Ctrl+s) 612 613\par 614Writes the current data to the <tt>.fl</tt> file. If the 615file is unnamed then FLUID will ask for a filename. 616 617\par File/Save As... (Ctrl+Shift+S) 618 619\par 620Asks for a new filename and saves the file. 621 622\par File/Write Code (Ctrl+Shift+C) 623 624\par 625"Compiles" the data into a <tt>.cxx</tt> and <tt>.h</tt> 626file. These are exactly the same as the files you get when you run 627FLUID with the \c -c switch. 628 629\par 630The output file names are the same as the <tt>.fl</tt> file, with 631the leading directory and trailing ".fl" stripped, and 632".h" or ".cxx" appended. 633 634\par File/Write Strings (Ctrl+Shift+W) 635 636\par 637Writes a message file for all of the text labels defined in 638the current file. 639 640\par 641The output file name is the same as the <tt>.fl</tt> file, 642with the leading directory and trailing ".fl" 643stripped, and ".txt", ".po", or ".msg" appended depending on the 644\ref fluid_i18n "Internationalization Mode". 645 646\par File/Quit (Ctrl+q) 647 648\par 649Exits FLUID. You are asked for confirmation if you have 650changed the current file. 651 652\par Edit/Undo (Ctrl+z) 653 654\par 655This isn't implemented yet. You should do save often so you can 656recover from any mistakes you make. 657 658\par Edit/Cut (Ctrl+x) 659 660\par 661Deletes the selected widgets and all of their children. 662These are saved to a "clipboard" file and can be 663pasted back into any FLUID window. 664 665\par Edit/Copy (Ctrl+c) 666 667\par 668Copies the selected widgets and all of their children to the 669"clipboard" file. 670 671\par Edit/Paste (Ctrl+c) 672 673\par 674Pastes the widgets from the clipboard file. 675 676\par 677If the widget is a window, it is added to whatever function 678is selected, or contained in the current selection. 679 680\par 681If the widget is a normal widget, it is added to whatever 682window or group is selected. If none is, it is added to the 683window or group that is the parent of the current selection. 684 685\par 686To avoid confusion, it is best to select exactly one widget 687before doing a paste. 688 689\par 690Cut/paste is the only way to change the parent of a 691widget. 692 693\par Edit/Select All (Ctrl+a) 694 695\par 696Selects all widgets in the same group as the current selection. 697 698\par 699If they are all selected already then this selects all 700widgets in that group's parent. Repeatedly typing Ctrl+a will 701select larger and larger groups of widgets until everything is 702selected. 703 704\par Edit/Open... (F1 or double click) 705 706\par 707Displays the current widget in the attributes panel. If the 708widget is a window and it is not visible then the window is 709shown instead. 710 711\par Edit/Sort 712 713\par 714Sorts the selected widgets into left to right, top to bottom 715order. You need to do this to make navigation keys in FLTK work 716correctly. You may then fine-tune the sorting with 717"Earlier" and "Later". This does not affect 718the positions of windows or functions. 719 720\par Edit/Earlier (F2) 721 722\par 723Moves all of the selected widgets one earlier in order among 724the children of their parent (if possible). This will affect 725navigation order, and if the widgets overlap it will affect how 726they draw, as the later widget is drawn on top of the earlier 727one. You can also use this to reorder functions, classes, and 728windows within functions. 729 730\par Edit/Later (F3) 731 732\par 733Moves all of the selected widgets one later in order among 734the children of their parent (if possible). 735 736\par Edit/Group (F7) 737 738\par 739Creates a new Fl_Group and make all the currently 740selected widgets children of it. 741 742\par Edit/Ungroup (F8) 743 744\par 745Deletes the parent group if all the children of a group are 746selected. 747 748\par Edit/Overlays on/off (Ctrl+Shift+O) 749 750\par 751Toggles the display of the red overlays off, without changing 752the selection. This makes it easier to see box borders and how 753the layout looks. The overlays will be forced back on if you 754change the selection. 755 756\par Edit/Project Settings... (Alt+p) 757 758\par 759Displays the project settings panel. 760 761\par 762Under the "Output" tab you control the extensions or names of the files 763that are generated by FLUID. If you check the "Include Header from Code" 764button the code file will include the header file automatically. 765 766\par 767Under the "Internationalization" tab are the \ref fluid_i18n "internationalization" 768options, described later in this chapter. 769 770\image html fluid-edit-proj-settings.png "Figure 9-7: FLUID Project Settings Window" 771\image latex fluid-edit-proj-settings.png "FLUID Project Settings Window" width=10cm 772 773\par Edit/GUI Settings... (Shift+Alt+p) 774 775\par 776Displays the GUI Settings panel, used to control the user interface settings. 777 778\image html fluid-edit-gui-settings.png "Figure 9-7a: FLUID GUI Settings Window" 779\image latex fluid-edit-gui-settings.png "FLUID GUI Settings Window" width=10cm 780 781\par Edit/Global FLTK Settings... (Shift+Alt+g) 782 783\par 784Displays the FLTK Global Settings ("Preferences") panel, used to control fluid's 785user specific and/or system wide settings. 786 787\par 788Tooltips provide descriptions of each option. 789 790\par 791At the lower-right, "User Settings" causes changes to only affect the current user, 792"System Settings" causes changes to be applied to all users on the current machine. 793 794\image html fluid-edit-global-fltk-settings.png "Figure 9-7b: FLUID Global Settings Window" 795\image latex fluid-edit-global-fltk-settings.png "FLUID Global Settings Window" width=10cm 796 797\par New/Code/Function 798 799\par 800Creates a new C function. You will be asked for a name for 801the function. This name should be a legal C++ function 802template, without the return type. You can pass arguments which 803can be referred to by code you type into the individual widgets. 804 805\par 806If the function contains any unnamed windows, it will be 807declared as returning a Fl_Window pointer. The unnamed window 808will be returned from it (more than one unnamed window is 809useless). If the function contains only named windows, it will 810be declared as returning nothing (\c void ). 811 812\par 813It is possible to make the <tt>.cxx</tt> output be a 814self-contained program that can be compiled and executed. This 815is done by deleting the function name so 816\p main(argc,argv) is used. The function will call 817\p show() on all the windows it creates and then call 818\p Fl::run(). This can also be used to test resize 819behavior or other parts of the user interface. 820 821\par 822You can change the function name by double-clicking on the 823function. 824 825\par New/Window 826 827\par 828Creates a new Fl_Window widget. The window is added 829to the currently selected function, or to the function 830containing the currently selected item. The window will appear, 831sized to 100x100. You can resize it to whatever size you 832require. 833 834\par 835The widget panel will also appear and is described later in 836this chapter. 837 838\par New/... 839 840\par 841All other items on the New menu are subclasses of 842Fl_Widget. Creating them will add them to the 843currently selected group or window, or the group or window 844containing the currently selected widget. The initial 845dimensions and position are chosen by copying the current 846widget, if possible. 847 848\par 849When you create the widget you will get the widget's control 850panel, which is described later in this chapter. 851 852\par Layout/Align/... 853 854\par 855Align all selected widgets to the first widget in the selection. 856 857\par Layout/Space Evenly/... 858 859\par 860Space all selected widgets evenly inside the selected space. 861Widgets will be sorted from first to last. 862 863\par Layout/Make Same Size/... 864 865\par 866Make all selected widgets the same size as the first selected widget. 867 868\par Layout/Center in Group/... 869 870\par 871Center all selected widgets relative to their parent widget 872 873\par Layout/Grid and Size Settings... (Ctrl+g) 874 875\par 876Displays the grid settings panel. 877 878\par 879This panel controls the grid that all widgets snap to when you move 880and resize them, and for the "snap" which is how far a widget has to be 881dragged from its original position to actually change. 882 883\image html fluid-layout-grid-and-size-settings.png "Figure 9-7c: FLUID Layout/Grid Settings Window" 884\image latex fluid-layout-grid-and-size-settings.png "FLUID Layout/Grid Settings Window" width=10cm 885 886\par Shell/Execute Command... (Alt+x) 887 888\par 889Displays the shell command panel. The shell command 890is commonly used to run a 'make' script to compile the FLTK output. 891 892\par Shell/Execute Again (Alt+g) 893 894\par 895Run the shell command again. 896 897\par Help/About FLUID 898 899\par 900Pops up a panel showing the version of FLUID. 901 902\par Help/On FLUID 903 904\par 905Shows this chapter of the manual. 906 907\par Help/Manual 908 909\par 910Shows the contents page of the manual 911 912\subsection fluid_widget_panel The Widget Panel 913 914When you double-click on a widget or a set of widgets you 915will get the "widget attribute panel". 916 917When you change attributes using this panel, the changes are 918reflected immediately in the window. It is useful to hit the 919"no overlay" button (or type Ctrl+Shift+O) to hide the 920red overlay so you can see the widgets more accurately, 921especially when setting the box type. 922 923If you have several widgets selected, they may have different 924values for the fields. In this case the value for \e one of 925the widgets is shown. But if you change this value, \e all 926of the selected widgets are changed to the new value. 927 928Hitting "OK" makes the changes permanent. 929Selecting a different widget also makes the changes permanent. 930FLUID checks for simple syntax errors such as mismatched 931parenthesis in any code before saving any text. 932 933"Revert" or "Cancel" put everything back 934to when you last brought up the panel or hit OK. However in the 935current version of FLUID, changes to "visible" 936attributes (such as the color, label, box) are not undone by 937revert or cancel. Changes to code like the callbacks are 938undone, however. 939 940<!-- NEW PAGE --> 941 942\image html fluid_widget_gui.png "Figure 9-8: The FLUID widget GUI attributes" 943\image latex fluid_widget_gui.png "The FLUID widget GUI attributes" width=10cm 944 945\section fluid_widget_attributes GUI Attributes 946 947\par Label (text field) 948 949\par 950String to print next to or inside the button. You can put 951newlines into the string to make multiple lines. The easiest way 952is by typing Ctrl+j. 953 954\par 955\ref common_labels "Symbols" 956can be added to the label using the at sign ("@"). 957 958\par Label (pull down menu) 959 960\par 961How to draw the label. Normal, shadowed, engraved, and 962embossed change the appearance of the text. 963 964\par Image 965 966\par 967The active image for the widget. Click on the 968\b Browse... button to pick an image file using the file 969chooser. 970 971\par Inactive 972 973\par 974The inactive image for the widget. Click on the 975\b Browse... button to pick an image file using the file 976chooser. 977 978\par Alignment (buttons) 979 980\par 981Where to draw the label. The arrows put it on that side of the 982widget, you can combine them to put it in the corner. The "box" 983button puts the label inside the widget, rather than outside. 984 985\par 986The \b clip button clips the label to the widget box, the 987\b wrap button wraps any text in the label, and the 988<b>text image</b> button puts the text over the image instead of under 989the image. 990 991\par Position (text fields) 992 993\par 994The position fields show the current position and size of the 995widget box. Enter new values to move and/or resize a widget. 996 997\par Values (text fields) 998 999\par 1000The values and limits of the current widget. Depending on the 1001type of widget, some or all of these fields may be inactive. 1002 1003\par Shortcut 1004 1005\par 1006The shortcut key to activate the widget. Click on the 1007shortcut button and press any key sequence to set the shortcut. 1008 1009\par Attributes (buttons) 1010 1011\par 1012The \b Visible button controls whether the widget is 1013visible (on) or hidden (off) initially. Don't change this for 1014windows or for the immediate children of a Tabs group. 1015 1016\par 1017The \b Active button controls whether the widget is 1018activated (on) or deactivated (off) initially. Most widgets 1019appear greyed out when deactivated. 1020 1021\par 1022The \b Resizable button controls whether the window is 1023resizeable. In addition all the size changes of a window or 1024group will go "into" the resizable child. If you have 1025a large data display surrounded by buttons, you probably want 1026that data area to be resizable. You can get more complex 1027behavior by making invisible boxes the resizable widget, or by 1028using hierarchies of groups. Unfortunately the only way to test 1029it is to compile the program. Resizing the FLUID window is 1030\e not the same as what will happen in the user program. 1031 1032\par 1033The \b Hotspot button causes the parent window to be 1034positioned with that widget centered on the mouse. This 1035position is determined <i>when the FLUID function is called</i>, 1036so you should call it immediately before showing the window. If 1037you want the window to hide and then reappear at a new position, 1038you should have your program set the hotspot itself just before 1039\p show(). 1040 1041\par 1042The \b Border button turns the window manager border on 1043or off. On most window managers you will have to close the 1044window and reopen it to see the effect. 1045 1046\par X Class (text field) 1047 1048\par 1049The string typed into here is passed to the X window manager 1050as the class. This can change the icon or window decorations. 1051On most (all?) window managers you will have to close the window 1052and reopen it to see the effect. 1053 1054\image html fluid_widget_style.png "Figure 9-9: The FLUID widget Style attributes" 1055\image latex fluid_widget_style.png "The FLUID widget Style attributes" width=10cm 1056 1057\subsection fluid_style_attributes Style Attributes 1058 1059\par Label Font (pulldown menu) 1060 1061\par 1062Font to draw the label in. Ignored by symbols, bitmaps, and 1063pixmaps. Your program can change the actual font used by these 1064"slots" in case you want some font other than the 16 1065provided. 1066 1067\par Label Size (pulldown menu) 1068 1069\par 1070Pixel size (height) for the font to draw the label in. 1071Ignored by symbols, bitmaps, and pixmaps. To see the result 1072without dismissing the panel, type the new number and then Tab. 1073 1074\par Label Color (button) 1075 1076\par 1077Color to draw the label. Ignored by pixmaps (bitmaps, 1078however, do use this color as the foreground color). 1079 1080\par Box (pulldown menu) 1081 1082\par 1083The boxtype to draw as a background for the widget. 1084 1085\par 1086Many widgets will work, and draw faster, with a 1087"frame" instead of a "box". A frame does 1088not draw the colored interior, leaving whatever was already 1089there visible. Be careful, as FLUID may draw this ok but the 1090real program may leave unwanted stuff inside the widget. 1091 1092\par 1093If a window is filled with child widgets, you can speed up 1094redrawing by changing the window's box type to 1095"NO_BOX". FLUID will display a checkerboard for any 1096areas that are not colored in by boxes. Note that this 1097checkerboard is not drawn by the resulting program. Instead 1098random garbage will be displayed. 1099 1100\par Down Box (pulldown menu) 1101 1102\par 1103The boxtype to draw when a button is pressed or for some 1104parts of other widgets like scrollbars and valuators. 1105 1106\par Color (button) 1107 1108\par 1109The color to draw the box with. 1110 1111\par Select Color (button) 1112 1113\par 1114Some widgets will use this color for certain parts. FLUID 1115does not always show the result of this: this is the color 1116buttons draw in when pushed down, and the color of input fields 1117when they have the focus. 1118 1119\par Text Font, Size, and Color 1120 1121\par 1122Some widgets display text, such as input fields, pull-down 1123menus, and browsers. 1124 1125\image html fluid_widget_cxx.png "Figure 9-10: The FLUID widget C++ attributes" 1126\image latex fluid_widget_cxx.png "The FLUID widget C++ attributes" width=10cm 1127 1128\subsection fluid_cpp_attributes C++ Attributes 1129 1130\par Class 1131 1132\par 1133This is how you use your own subclasses of 1134Fl_Widget. Whatever identifier you type in here will 1135be the class that is instantiated. 1136 1137\par 1138In addition, no \p \#include header file is put in the 1139<tt>.h</tt> file. You must provide a \p \#include line as 1140the first line of the "Extra Code" which declares your 1141subclass. 1142 1143\par 1144The class must be similar to the class you are spoofing. It 1145does not have to be a subclass. It is sometimes useful to 1146change this to another FLTK class. Currently the only way to get 1147a double-buffered window is to change this field for the window 1148to "Fl_Double_Window" and to add 1149\code #include <FL/Fl_Double_Window.h> \endcode 1150to the extra code. 1151 1152\par Type (upper-right pulldown menu) 1153 1154\par 1155Some classes have subtypes that modify their appearance or behavior. 1156You pick the subtype off of this menu. 1157 1158\par Name (text field) 1159 1160\par 1161Name of a variable to declare, and to store a pointer to this 1162widget into. This variable will be of type "<class>*". If the name is 1163blank then no variable is created. 1164 1165\par 1166You can name several widgets with "name[0]", "name[1]", "name[2]", 1167etc. This will cause FLUID to declare an array of pointers. The array 1168is big enough that the highest number found can be stored. All widgets 1169in the array must be the same type. 1170 1171\par Public (button) 1172 1173\par 1174Controls whether the widget is publicly accessible. When 1175embedding widgets in a C++ class, this controls whether the 1176widget is \p public or \p private in the class. 1177Otherwise it controls whether the widget is declared 1178\p static or global (\p extern ). 1179 1180\par Extra Code (text fields) 1181 1182\par 1183These four fields let you type in literal lines of code to 1184dump into the <tt>.h</tt> or <tt>.cxx</tt> files. 1185 1186\par 1187If the text starts with a <tt>\#</tt> or the word 1188\p extern then FLUID thinks this is an "include" 1189line, and it is written to the <tt>.h</tt> file. If the same 1190include line occurs several times then only one copy is 1191written. 1192 1193\par 1194All other lines are "code" lines. The current 1195widget is pointed to by the local variable \p o. The 1196window being constructed is pointed to by the local variable 1197\p w. You can also access any arguments passed to the 1198function here, and any named widgets that are before this 1199one. 1200 1201\par 1202FLUID will check for matching parenthesis, braces, and 1203quotes, but does not do much other error checking. Be careful 1204here, as it may be hard to figure out what widget is producing 1205an error in the compiler. If you need more than four lines you 1206probably should call a function in your own <tt>.cxx</tt> 1207code. 1208 1209\par Callback (text field) 1210 1211\par 1212This can either be the name of a function, or a small snippet 1213of code. If you enter anything other than letters, numbers, and the 1214underscore then FLUID treats it as code. 1215 1216\par 1217A name refers to a function in your own code. It must be 1218declared as <tt>void name(<class>*,void*)</tt>. 1219 1220\par 1221A code snippet is inserted into a static function in the 1222<tt>.cxx</tt> output file. The function prototype is 1223<tt>void name(class *o, void *v)</tt> 1224so that you can refer to the widget as \p o and the \p user_data() 1225as \p v. FLUID will check for matching parenthesis, braces, 1226and quotes, but does not do much other error checking. Be 1227careful here, as it may be hard to figure out what widget is 1228producing an error in the compiler. 1229 1230\par 1231If the callback is blank then no callback is set. 1232 1233\par User Data (text field) 1234 1235\par 1236This is a value for the \p user_data() of the widget. 1237If blank the default value of zero is used. This can be any 1238piece of C code that can be cast to a \p void pointer. 1239 1240\par Type (text field) 1241 1242\par 1243The \p void* in the callback function prototypes is 1244replaced with this. You may want to use \p long for old 1245XForms code. Be warned that anything other than \p void* 1246is not guaranteed to work! However on most architectures other 1247pointer types are ok, and \p long is usually ok, too. 1248 1249\par When (pulldown menu) 1250 1251\par 1252When to do the callback. This can be \b Never, 1253\b Changed, \b Release, or \b Enter Key. The value of 1254<b>Enter Key</b> is only useful for text input fields. 1255 1256\par 1257There are other rare but useful values for the 1258\p when() field that are not in the menu. You should use 1259the extra code fields to put these values in. 1260 1261\par No Change (button) 1262 1263\par 1264The <b>No Change</b> button means the callback is done on the 1265matching event even if the data is not changed. 1266 1267\section fluid_selecting_moving Selecting and Moving Widgets 1268 1269Double-clicking a window name in the browser will display it, 1270if not displayed yet. From this display you can select widgets, 1271sets of widgets, and move or resize them. To close a window 1272either double-click it or type \c ESC. 1273 1274To select a widget, click it. To select several widgets drag 1275a rectangle around them. Holding down shift will toggle the 1276selection of the widgets instead. 1277 1278You cannot pick hidden widgets. You also cannot choose some 1279widgets if they are completely overlapped by later widgets. Use 1280the browser to select these widgets. 1281 1282The selected widgets are shown with a red "overlay" 1283line around them. You can move the widgets by dragging this 1284box. Or you can resize them by dragging the outer edges and 1285corners. Hold down the Alt key while dragging the mouse to 1286defeat the snap-to-grid effect for fine positioning. 1287 1288If there is a tab box displayed you can change which child is 1289visible by clicking on the file tabs. The child you pick is 1290selected. 1291 1292The arrow, tab, and shift+tab keys "navigate" the 1293selection. Left, right, tab, or shift+tab move to the next or 1294previous widgets in the hierarchy. Hit the right arrow enough 1295and you will select every widget in the window. Up/down widgets 1296move to the previous/next widgets that overlap horizontally. If 1297the navigation does not seem to work you probably need to 1298"Sort" the widgets. This is important if you have 1299input fields, as FLTK uses the same rules when using arrow keys 1300to move between input fields. 1301 1302To "open" a widget, double click it. To open 1303several widgets select them and then type F1 or pick 1304"Edit/Open" off the pop-up menu. 1305 1306Type Ctrl+o to temporarily toggle the overlay off without 1307changing the selection, so you can see the widget borders. 1308 1309You can resize the window by using the window manager border 1310controls. FLTK will attempt to round the window size to the 1311nearest multiple of the grid size and makes it big enough to 1312contain all the widgets (it does this using illegal X methods, 1313so it is possible it will barf with some window managers!). 1314Notice that the actual window in your program may not be 1315resizable, and if it is, the effect on child widgets may be 1316different. 1317 1318The panel for the window (which you get by double-clicking 1319it) is almost identical to the panel for any other Fl_Widget. 1320There are three extra items: 1321 1322\section fluid_images Image Labels 1323 1324The \e contents of the image files in the \b Image 1325and \b Inactive text fields are written to the <tt>.cxx</tt> 1326file. If many widgets share the same image then only one copy is 1327written. Since the image data is embedded in the generated 1328source code, you need only distribute the C++ code and not the 1329image files themselves. 1330 1331However, the \e filenames are stored in the <tt>.fl</tt> 1332file so you will need the image files as well to read the 1333<tt>.fl</tt> file. Filenames are relative to the location of the 1334<tt>.fl</tt> file and not necessarily the current directory. We 1335recommend you either put the images in the same directory as the 1336<tt>.fl</tt> file, or use absolute path names. 1337 1338\par Notes for All Image Types 1339 1340\par 1341FLUID runs using the default visual of your X server. This 1342may be 8 bits, which will give you dithered images. You may get 1343better results in your actual program by adding the code 1344"Fl::visual(FL_RGB)" to your code right before the 1345first window is displayed. 1346 1347\par 1348All widgets with the same image on them share the same code 1349and source X pixmap. Thus once you have put an image on a 1350widget, it is nearly free to put the same image on many other 1351widgets. 1352 1353\par 1354If you edit an image at the same time you are using it in FLUID, 1355the only way to convince FLUID to read the image file again is to 1356remove the image from all widgets that are using it or re-load the 1357<tt>.fl</tt> file. 1358 1359\par 1360Don't rely on how FLTK crops images that are outside the 1361widget, as this may change in future versions! The cropping of 1362inside labels will probably be unchanged. 1363 1364\par 1365To more accurately place images, make a new "box" 1366widget and put the image in that as the label. 1367 1368\par XBM (X Bitmap) Files 1369 1370\par 1371FLUID reads X bitmap files which use C source code to define 1372a bitmap. Sometimes they are stored with the ".h" or 1373".bm" extension rather than the standard 1374".xbm" extension. 1375 1376\par 1377FLUID writes code to construct an Fl_Bitmap image and use it 1378to label the widget. The '1' bits in the bitmap are drawn using 1379the label color of the widget. You can change this color in the 1380FLUID widget attributes panel. The '0' bits are transparent. 1381 1382\par 1383The program "bitmap" on the X distribution does an 1384adequate job of editing bitmaps. 1385 1386\par XPM (X Pixmap) Files 1387 1388\par 1389FLUID reads X pixmap files as used by the \p libxpm 1390library. These files use C source code to define a pixmap. The 1391filenames usually have the ".xpm" extension. 1392 1393\par 1394FLUID writes code to construct an Fl_Pixmap image and use it 1395to label the widget. The label color of the widget is ignored, 1396even for 2-color images that could be a bitmap. XPM files can 1397mark a single color as being transparent, and FLTK uses this 1398information to generate a transparency mask for the image. 1399 1400\par 1401We have not found any good editors for small iconic pictures. 1402For pixmaps we have used 1403<A href="http://home.worldonline.dk/~torsten/xpaint/index.html">XPaint</A> 1404and the KDE icon editor. 1405 1406\par BMP Files 1407 1408\par 1409FLUID reads Windows BMP image files which are often used in 1410WIN32 applications for icons. FLUID converts BMP files into 1411(modified) XPM format and uses a Fl_BMP_Image image to label the 1412widget. Transparency is handled the same as for XPM files. All 1413image data is uncompressed when written to the source file, so 1414the code may be much bigger than the <tt>.bmp</tt> file. 1415 1416\par GIF Files 1417 1418\par 1419FLUID reads GIF image files which are often used in HTML 1420documents to make icons. FLUID converts GIF files into 1421(modified) XPM format and uses a Fl_GIF_Image image to label the 1422widget. Transparency is handled the same as for XPM files. All 1423image data is uncompressed when written to the source file, so 1424the code may be much bigger than the <tt>.gif</tt> file. Only 1425the first image of an animated GIF file is used. 1426 1427\par JPEG Files 1428 1429\par 1430If FLTK is compiled with JPEG support, FLUID can read JPEG 1431image files which are often used for digital photos. FLUID uses 1432a Fl_JPEG_Image image to label the widget, and writes 1433uncompressed RGB or grayscale data to the source file. 1434 1435\par PNG (Portable Network Graphics) Files 1436 1437\par 1438If FLTK is compiled with PNG support, FLUID can read PNG 1439image files which are often used in HTML documents. FLUID uses a 1440Fl_PNG_Image image to label the widget, and writes uncompressed 1441RGB or grayscale data to the source file. PNG images can provide 1442a full alpha channel for partial transparency, and FLTK supports 1443this as best as possible on each platform. 1444 1445\section fluid_i18n Internationalization with FLUID 1446 1447FLUID supports internationalization (I18N for short) of label 1448strings used by widgets. The preferences window 1449(<tt>Ctrl+p</tt>) provides access to the I18N options. 1450 1451\subsection fluid_i18n_methods I18N Methods 1452 1453FLUID supports three methods of I18N: use none, use GNU 1454gettext, and use POSIX catgets. The "use none" method is the 1455default and just passes the label strings as-is to the widget 1456constructors. 1457 1458The "GNU gettext" method uses GNU gettext (or a similar 1459text-based I18N library) to retrieve a localized string before 1460calling the widget constructor. 1461 1462The "POSIX catgets" method uses the POSIX catgets function to 1463retrieve a numbered message from a message catalog before 1464calling the widget constructor. 1465 1466\subsection fluid_gettext_i18n Using GNU gettext for I18N 1467 1468FLUID's code support for GNU gettext is limited to calling a 1469function or macro to retrieve the localized label; you still 1470need to call \p setlocale() and \p textdomain() or 1471\p bindtextdomain() to select the appropriate language and 1472message file. 1473 1474To use GNU gettext for I18N, open the preferences window and 1475choose "GNU gettext" from the \b Use: chooser. Two new input 1476fields will then appear to control the include file and 1477function/macro name to use when retrieving the localized label 1478strings. 1479 1480 \image html fluid-gettext.png "Figure 9-11: Internationalization using GNU gettext" 1481 \image latex fluid-gettext.png "Internationalization using GNU gettext" width=10cm 1482 1483The \b \#include 1484field controls the header file to include for 1485I18N; by default this is \b <libintl.h>, the 1486standard I18N file for GNU gettext. 1487 1488The \b Function: field controls the function (or macro) that 1489will retrieve the localized message; by default the 1490\p gettext function will be called. 1491 1492\subsection fluid_catgets_i18n Using POSIX catgets for I18N 1493 1494FLUID's code support for POSIX catgets allows you to use a 1495global message file for all interfaces or a file specific to 1496each <tt>.fl</tt> file; you still need to call 1497\p setlocale() to select the appropriate language. 1498 1499To use POSIX catgets for I18N, open the preferences window 1500and choose "POSIX catgets" from the \b Use: chooser. Three new 1501input fields will then appear to control the include file, 1502catalog file, and set number for retrieving the localized label 1503strings. 1504 1505 \image html fluid-catgets.png "Figure 9-12: Internationalization using POSIX catgets" 1506 \image latex fluid-catgets.png "Internationalization using POSIX catgets" width=10cm 1507 1508The \b \#include 1509field controls the header file to include for 1510I18N; by default this is \b <nl_types.h>, the 1511standard I18N file for POSIX catgets. 1512 1513The \b File: field controls the name of the catalog file 1514variable to use when retrieving localized messages; by default 1515the file field is empty which forces a local (static) catalog 1516file to be used for all of the windows defined in your 1517<tt>.fl</tt> file. 1518 1519The \b Set: field controls the set number in the catalog file. 1520The default set is 1 and rarely needs to be changed. 1521 1522\section fluid_limitations Known limitations 1523 1524Declaration Blocks can be used to temporarily block out already 1525designed code using <tt>\#if 0</tt> and <tt>\#endif</tt> 1526type construction. This will effectively avoid compilation of 1527blocks of code. However, static code and data generated by this 1528segment (menu items, images, include statements, etc.) will still 1529be generated and likely cause compile-time warnings. 1530 1531 1532\htmlonly 1533<hr> 1534<table summary="navigation bar" width="100%" border="0"> 1535<tr> 1536 <td width="45%" align="LEFT"> 1537 <a class="el" href="opengl.html"> 1538 [Prev] 1539 Using OpenGL 1540 </a> 1541 </td> 1542 <td width="10%" align="CENTER"> 1543 <a class="el" href="index.html">[Index]</a> 1544 </td> 1545 <td width="45%" align="RIGHT"> 1546 <a class="el" href="advanced.html"> 1547 Advanced FLTK 1548 [Next] 1549 </a> 1550 </td> 1551</tr> 1552</table> 1553\endhtmlonly 1554 1555*/ 1556