From a9103714031cedb16b00cd6ce81ef93b04734f08 Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Wed, 12 Dec 2001 15:20:27 +0000 Subject: [PATCH] Documentation updates, mainly to fix typos, mark constants with TT, and clean up the osissues.html file for all OS's. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@1836 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/Fl.html | 2 +- documentation/intro.html | 12 +- documentation/osissues.html | 844 ++++++++++++++++++++++-------------- documentation/preface.html | 17 +- 4 files changed, 535 insertions(+), 340 deletions(-) diff --git a/documentation/Fl.html b/documentation/Fl.html index 03fe903b9..8bc5728bc 100644 --- a/documentation/Fl.html +++ b/documentation/Fl.html @@ -1081,7 +1081,7 @@ seconds. It can return much sooner if something happens.

The return value is positive if an event or fd happens before the time elapsed. It is zero if nothing happens (on Win32 this will only return zero if time is zero). It is negative if an error -occurs (this will happen on Unix if a signal happens). +occurs (this will happen on UNIX if a signal happens).

void (*warning)(const char*, ...);

diff --git a/documentation/intro.html b/documentation/intro.html index ba1af584b..f933c2934 100644 --- a/documentation/intro.html +++ b/documentation/intro.html @@ -5,7 +5,7 @@

The Fast Light Tool Kit ("FLTK", pronounced "fulltick") is a LGPL'd C++ graphical user interface -toolkit for X (UNIX®), OpenGL®, MacOS® X, and +toolkit for X (UNIX®), OpenGL®, MacOS®, and Microsoft® Windows®. It was originally developed by Mr. Bill Spitzak and is currently maintained by a small group of developers across the world with a central repository in the @@ -98,12 +98,12 @@ is now included with several Linux distributions.

  • The FLUID program (which includes every widget) is 538k.
    • -
  • Written directly atop core libraries (Xlib, WIN32 or Carbon) for maximum - speed, and carefully optimized for code size and - performance.
    • +
  • Written directly atop core libraries (Xlib, WIN32 or + Carbon) for maximum speed, and carefully optimized for + code size and performance.
  • Precise low-level compatability between the X11, - WIN32 and MacOS version - only about 10% of the code is + WIN32 and MacOS versions - only about 10% of the code is different.
  • Interactive user interface builder program. Output is @@ -113,7 +113,7 @@ is now included with several Linux distributions.

    is available.
  • Very small & fast portable 2-D drawing library - to hide Xlib, WIN32 or QuickDraw.
    • + to hide Xlib, WIN32, or QuickDraw.
  • OpenGL/Mesa drawing area widget.
    • diff --git a/documentation/osissues.html b/documentation/osissues.html index f67016058..e454bb5a3 100644 --- a/documentation/osissues.html +++ b/documentation/osissues.html @@ -1,131 +1,208 @@ - -

    F - Operating System Issues

    - This appendix describes the X and WIN32 specific interfaces in FLTK. -

    X-Specific Interface

    - + +

    Despite the name, this header file will define the +appropriate interface for your environment. The pages that +follow describe the functionality that is provided for each +operating system. + +

    + + + +
    WARNING: + +

    The interfaces provided by this header file may + change radically in new FLTK releases. Use them only + when an existing generic FLTK interface is not + sufficient.

    + +
    + +

    The UNIX (X11) Interface

    + +

    The UNIX interface provides access to the X Window System +state information and data structures. +

    Handling Other X Events

    -

    void Fl::add_handler(int (*f)(int))

    - Installs a function to parse unrecognized events. If FLTK cannot -figure out what to do with an event, it calls each of these functions -(most recent first) until one of them returns non-zero. If none of -them returns non-zero then the event is ignored. -

    FLTK calls this for any X events it does not recognize, or X events -with a window id that FLTK does not recognize. You can look at the X -event with the fl_xevent variable.

    -

    The argument is zero for unrecognized X events. These handlers are -also called for global shortcuts and some other events that the widget -they were passed to did not handle. In this case the argument is -non-zero (for example FL_SHORTCUT).

    -

    extern XEvent *fl_xvent

    - The most recent X event. -

    extern ulong fl_event_time

    - This is the time stamp from the most recent X event that reported it -(not all do). Many X calls (like cut and paste) need this value. -

    Window fl_xid(const Fl_Window *)

    - Returns the XID for a window, or zero if not shown(). -

    Fl_Window *fl_find(ulong xid)

    - Returns the Fl_Window that corresponds to the given XID, or -NULL if not found. This uses a cache so it is slightly faster -than iterating through the windows yourself. -

    int fl_handle(const XEvent &)

    - This call allows you to supply the X events to FLTK, which may allow -FLTK to cooperate with another toolkit or library. The return value is -true if FLTK understood the event (if the window does not belong to -FLTK and the add_handler() functions all ignore it this -returns false). -

    Besides feeding events your code should call -Fl::flush() periodically so that FLTK redraws its windows.

    -

    This function will call the callback functions. It will not return -until they complete. In particular if a callback pops up a modal -window (by calling fl_ask(), -for instance) it will not return until the modal function returns.

    + +

    void Fl::add_handler(int (*f)(int))

    + +

    Installs a function to parse unrecognized events. If FLTK +cannot figure out what to do with an event, it calls each of +these functions (most recent first) until one of them returns +non-zero. If none of them returns non-zero then the event is +ignored. + +

    FLTK calls this for any X events it does not recognize, or X +events with a window ID that FLTK does not recognize. You can +look at the X event in the fl_xevent variable.

    + +

    The argument is the FLTK event type that was not handled, or +zero for unrecognized X events. These handlers are also called +for global shortcuts and some other events that the widget they +were passed to did not handle, for example +FL_SHORTCUT.

    + +

    extern XEvent *fl_xvent

    + +

    This variable contains the most recent X event. + +

    extern ulong fl_event_time

    + +

    This variable contains the time stamp from the most recent X +event that reported it; not all events do. Many X calls like cut +and paste need this value. + +

    Window fl_xid(const Fl_Window *)

    + +

    Returns the XID for a window, or zero if not shown(). + +

    Fl_Window *fl_find(ulong xid)

    + +

    Returns the Fl_Window that corresponds to the given +XID, or NULL if not found. This function uses a cache +so it is slightly faster than iterating through the windows +yourself.

    + +

    int fl_handle(const XEvent &)

    + +

    This call allows you to supply the X events to FLTK, which +may allow FLTK to cooperate with another toolkit or library. The +return value is non-zero if FLTK understood the event. If the +window does not belong to FLTK and the add_handler() +functions all return 0, this function will return false. + +

    Besides feeding events your code should call Fl::flush() +periodically so that FLTK redraws its windows.

    + +

    This function will call the callback functions. It will not +return until they complete. In particular, if a callback pops up +a modal window by calling fl_ask(), for +instance, it will not return until the modal function +returns.

    +

    Drawing using Xlib

    - The following global variables are set before Fl_Widget::draw() - is called, or by -Fl_Window::make_current(): - + +

    Other information such as the position or size of the X +window can be found by looking at Fl_Window::current(), +which returns a pointer to the Fl_Window being drawn. + +

    unsigned long fl_xpixel(Fl_Color i)
    +unsigned long fl_xpixel(uchar r, uchar g, uchar b)

    + +

    Returns the X pixel number used to draw the given FLTK color +index or RGB color. This is the X pixel that fl_color() would use. + +

    extern XFontStruct *fl_xfont

    + +

    Points to the font selected by the most recent fl_font(). This is not +necessarily the current font of fl_gc, which is not set +until fl_draw() is +called. +

    Changing the Display, Screen, or X Visual

    - FLTK uses only a single display, screen, X visual, and X colormap. -This greatly simplifies its internal structure and makes it much -smaller and faster. You can change which it uses by setting global -variables before the first Fl_Window::show() is called. -You may also want to call Fl::visual() -, which is a portable interface to get a full color and/or double -buffered visual. -

    int Fl::display(const char *)

    - Set which X display to use. This actually does -putenv("DISPLAY=...") so that child programs will display on the -same screen if called with exec(). This must be done before -the display is opened. This call is provided under WIN32 but it has no -effect. -

    extern Display *fl_display

    - The open X display. This is needed as an argument to most Xlib calls. -Don't attempt to change it! This is NULL before the display -is opened. -

    void fl_open_display()

    - Opens the display. Does nothing if it is already open. This will -make sure fl_display is non-zero. You should call this if you -wish to do X calls and there is a chance that your code will be called -before the first show() of a window. -

    This may call Fl::abort() if there is an error opening the -display.

    -

    void fl_close_display()

    - This closes the X connection. You do not need to call this to -exit, and in fact it is faster to not do so! It may be useful to call -this if you want your program to continue without the X connection. You -cannot open the display again, and probably cannot call any FLTK -functions. -

    extern int fl_screen

    - Which screen number to use. This is set by fl_open_display() - to the default screen. You can change it by setting this to a -different value immediately afterwards. It can also be set by changing -the last number in the Fl::display() string to "host:0,#". -

    extern XVisualInfo *fl_visual -
    extern Colormap fl_colormap

    - The visual and colormap that FLTK will use for all windows. These are -set by fl_open_display() to the default visual and colormap. - You can change them before calling show() on the first -window. Typical code for changing the default visual is: - +

    Using a Subclass of Fl_Window for Special X Stuff

    - FLTK can manage an X window on a different screen, visual and/or -colormap, you just can't use FLTK's drawing routines to draw into it. -But you can write your own draw() method that uses Xlib -(and/or OpenGL) calls only. -

    FLTK can also manage XID's provided by other libraries or programs, -and call those libraries when the window needs to be redrawn.

    -

    To do this, you need to make a subclass of -Fl_Window and override some of these virtual functions:

    + +

    FLTK can manage an X window on a different screen, visual +and/or colormap, you just can't use FLTK's drawing routines to +draw into it. But you can write your own draw() method +that uses Xlib (and/or OpenGL) calls only. + +

    FLTK can also manage XID's provided by other libraries or +programs, and call those libraries when the window needs to be +redrawn.

    + +

    To do this, you need to make a subclass of Fl_Window and +override some of these virtual functions:

    +

    virtual void Fl_Window::show()

    - If the window is already shown() this must cause it to be -raised, this can usually be done by calling Fl_Window::show(). - If not shown() your implementation must call either -Fl_X::set_xid() or Fl_X::make_xid(). -

    An example:

    - +

    Fl_X *Fl_X::set_xid(Fl_Window *, Window xid)

    - Allocate a hidden structure called an Fl_X, put the XID into -it, and set a pointer to it from the Fl_Window. This causes -Fl_Window::shown() to return true. -

    void Fl_X::make_xid(Fl_Window *, XVisualInfo *= fl_visual, Colormap -= fl_colormap)

    - This static method does the most onerous parts of creating an X -window, including setting the label, resize limitations, etc. It then -does Fl_X::set_xid() with this new window and maps the window. + +

    Allocate a hidden structure called an Fl_X, put the +XID into it, and set a pointer to it from the +Fl_Window. This causes Fl_Window::shown() to +return true. + +

    void Fl_X::make_xid(Fl_Window *, XVisualInfo *= fl_visual, +Colormap = fl_colormap)

    + +

    This static method does the most onerous parts of creating an +X window, including setting the label, resize limitations, etc. +It then does Fl_X::set_xid() with this new window and +maps the window. +

    virtual void Fl_Window::flush()

    - This virtual function is called by Fl::flush() to update the -window. For FLTK's own windows it does this by setting the global -variables fl_window and fl_gc and then calling the -draw() method. For your own windows you might just want to put -all the drawing code in here. -

    The X region that is a combination of all damage() calls -done so far is in Fl_X::i(this)->region. If NULL - then you should redraw the entire window. The undocumented function -fl_clip_region(XRegion) will initialize the FLTK clip stack with a -region or NULL for no clipping. You must set region to -NULL afterwards as fl_clip_region() now owns it and will -delete it when done.

    -

    If damage() FL_DAMAGE_EXPOSE then only X expose events have -happened. This may be useful if you have an undamaged image (such as a -backing buffer) around.

    -

    Here is a sample where an undamaged image is kept somewhere:

    - +

    virtual void Fl_Window::hide()

    - Destroy the window server copy of the window. Usually you will -destroy contexts, pixmaps, or other resources used by the window, and -then call Fl_Window::hide() to get rid of the main window -identified by xid(). If you override this, you must also -override the destructor as shown: - +

    virtual void Fl_Window::~Fl_Window()

    - Because of the way C++ works, if you override hide() you -must override the destructor as well (otherwise only the base class -hide() is called): - +

    Setting the Icon of a Window

    -FLTK currently supports setting a window's icon *before* it is shown -using the Fl_Window::icon() method. + +

    FLTK currently supports setting a window's icon *before* it +is shown using the Fl_Window::icon() method. +

    void Fl_Window::icon(char *)

    -Sets the icon for the window to the passed pointer. You will need to -cast the icon Pixmap to a char * when calling this -method. To set the icon using a bitmap compiled with your application -use: - -

    Note: you must call -Fl_Window::show(argc, argv) for the icon to be used. The -Fl_Window::show() method does not bind the icon to the window. +

    + + + +
    NOTE: + +

    You must call Fl_Window::show(argc, + argv) for the icon to be used. The + Fl_Window::show() method does not bind the icon + to the window. + +

    + +

    The Windows (WIN32) Interface

    + +

    The Windows interface provides access to the WIN32 GDI +state information and data structures. -

    WIN32-Specific Interface

    - - The <FL/x.H> header file defines the interface to FLTK's -WIN32-specific functions. Be warned that some of the structures and -calls in it are subject to change in future version of FLTK. Try to -avoid doing this so your code is portable.

    Handling Other WIN32 Messages

    - By default a single WNDCLASSEX called "FLTK" is created. All -Fl_Windows are of this class unless you use Fl_Window::xclass() -. The window class is created the first time Fl_Window::show() - is called. -

    You can probably combine FLTK with other libraries that make their -own WIN32 window classes. The easiest way is to call Fl::wait() -, it will call DispatchMessage for all messages to the other -windows. If necessary you can let the other library take over (as long -as it calls DispatchMessage()), but you will have to arrange -for the function Fl::flush() to be called regularily so that -widgets are updated, timeouts are handled, and the idle functions are -called.

    -

    extern MSG fl_msg

    - The most recent message read by GetMessage (which is called -by Fl::wait(). This may not -be the most recent message sent to an FLTK window, because silly WIN32 + +

    By default a single WNDCLASSEX called "FLTK" is +created. All Fl_Window's are of this class unless you +use Fl_Window::xclass(). The window class is created +the first time Fl_Window::show() is called. + +

    You can probably combine FLTK with other libraries that make +their own WIN32 window classes. The easiest way is to call +Fl::wait(), as it will call DispatchMessage +for all messages to the other windows. If necessary you can let +the other library take over as long as it calls +DispatchMessage(), but you will have to arrange for the +function Fl::flush() to be called regularly so that +widgets are updated, timeouts are handled, and the idle +functions are called.

    + +

    extern MSG fl_msg

    + +

    This variable contains the most recent message read by +GetMessage, which is called by Fl::wait(). This may not be the +most recent message sent to an FLTK window, because silly WIN32 calls the handle procedures directly for some events (sigh). -

    void Fl::add_handler(int (*f)(int))

    - Install a function to parse unrecognized messages sent to FLTK -windows. If FLTK cannot figure out what to do with a message, it calls -each of these functions (most recent first) until one of them returns -non-zero. The argument passed to the fuctions is zero. If all the -handlers return zero then FLTK calls DefWindowProc(). -

    HWND fl_xid(const Fl_Window *)

    - Returns the window handle for a Fl_Window, or zero if not -shown(). -

    Fl_Window *fl_find(HWND xid)

    - Return the Fl_Window that corresponds to the given window -handle, or NULL if not found. This uses a cache so it is -slightly faster than iterating through the windows yourself. + +

    void Fl::add_handler(int (*f)(int))

    + +

    Installs a function to parse unrecognized messages sent to +FLTK windows. If FLTK cannot figure out what to do with a +message, it calls each of these functions (most recent first) +until one of them returns non-zero. The argument passed to the +functions is the FLTK event that was not handled or zero for +unknown messages. If all the handlers return zero then FLTK +calls DefWindowProc(). + +

    HWND fl_xid(const Fl_Window *)

    + +

    Returns the window handle for a Fl_Window, or zero +if not shown(). + +

    Fl_Window *fl_find(HWND xid)

    + +

    Returns the Fl_Window that corresponds to the given +window handle, or NULL if not found. This function uses +a cache so it is slightly faster than iterating through the +windows yourself. +

    Drawing Things Using the WIN32 GDI

    - When the virtual function Fl_Widget::draw() is called, FLTK -has stashed in some global variables all the silly extra arguments you -need to make a proper GDI call. These are: - + +

    It may also be useful to refer to Fl_Window::current() +to get the window's size or position. +

    Setting the Icon of a Window

    - FLTK currently supports setting a window's icon *before* it is shown -using the Fl_Window::icon() method. + +

    FLTK currently supports setting a window's icon *before* it +is shown using the Fl_Window::icon() method. +

    void Fl_Window::icon(char *)

    - Sets the icon for the window to the passed pointer. You will need to -cast the HICON handle to a char * when calling this -method. To set the icon using an icon resource compiled with your -application use: - -You can also use the LoadImage() and related functions to load -specific resolutions or create the icon from bitmap data. +

    You can also use the LoadImage() and related +functions to load specific resolutions or create the icon from +bitmap data. -

    Note: you must call -Fl_Window::show(argc, argv) for the icon to be used. The -Fl_Window::show() method does not bind the icon to the window. +

    + + + +
    NOTE: + +

    You must call Fl_Window::show(argc, + argv) for the icon to be used. The + Fl_Window::show() method does not bind the icon + to the window. + +

    How to Not Get a MSDOS Console Window

    - WIN32 has a really stupid mode switch stored in the executables that -controls whether or not to make a console window. + +

    WIN32 has a really stupid mode switch stored in the +executables that controls whether or not to make a console +window. +

    To always get a console window you simply create a console -application (the "/SUBSYSTEM:CONSOLE" option for the linker). For a -GUI-only application create a WIN32 application (the -"/SUBSYSTEM:WINDOWS" option for the linker).

    -

    FLTK includes a WinMain() function that calls the ANSI -standard main() entry point for you. This function creates -a console window when you use the debug version of the library.

    -

    WIN32 applications without a console cannot write to stdout - or stderr, even if they are run from a console window. Any -output is silently thrown away.

    -

    Known Bugs

    - If a program is deactivated, Fl::wait() does not return until -it is activated again, even though many events are delivered to the -program. This can cause idle background processes to stop unexpectedly. - This also happens while the user is dragging or resizing windows or -otherwise holding the mouse down. I was forced to remove most of the -efficiency FLTK uses for redrawing in order to get windows to update -while being moved. This is a design error in WIN32 and probably -impossible to get around. -

    Fl_Gl_Window::can_do_overlay() returns true until the first -time it attempts to draw an overlay, and then correctly returns whether -or not there is overlay hardware.

    -

    Cut text contains ^J rather than ^M^J to break lines. This is a -feature, not a bug.

    -

    SetCapture (used by Fl::grab()) doesn't work, and -the main window title bar turns gray while menus are popped up.

    -

    FLUID does not support BMP files yet.

    +application (the "/SUBSYSTEM:CONSOLE" option for the +linker). For a GUI-only application create a WIN32 application +(the "/SUBSYSTEM:WINDOWS" option for the linker).

    -

    MacOS-specific interface

    -FLTK supports MacOS 8.6, MacOS 9 and Mac OS X using the Apple Carbon library. -When compiled with MPW or MetroWerks' CodeWarrior, application binaries in CFM format will -run on all the above systems without changes. -OS X's 'gcc' however creates Mach-O binaries which are not supported by +

    FLTK includes a WinMain() function that calls the +ANSI standard main() entry point for you. This +function creates a console window when you use the debug version +of the library.

    + +

    WIN32 applications without a console cannot write to +stdout or stderr, even if they are run from a +console window. Any output is silently thrown away. +Additionally, WIN32 applications are run in the background by +the console, although you can use "start /wait program" to run +them in the foreground.

    + +

    Known WIN32 Bugs and Problems

    + +

    The following is a list of known bugs and problems in the WIN32 +version of FLTK: + +

    + +

    The MacOS Interface

    + +

    FLTK supports MacOS 8.6, MacOS 9 and MacOS X using the Apple +Carbon library. When compiled with MPW or MetroWerks' +CodeWarrior, application binaries in CFM format will run on all +the above systems without changes. The OS X GNU (gcc) compiler, +however, creates Mach-O binaries which are not supported by MacOS 9 and earlier. -
    -

    #include <FL/x.H>
    -The <FL/x.H> header file defines the interface to FLTK's MacOS-specific -functions. Be warned that some of the structures and calls in it are -subject to change in future version of FLTK. Try to avoid doing this -so your code is portable. -

    WindowRef fl_xid(const Fl_Window *)

    -Returns the window reference for an Fl_Window, or NULL if not shown. -

    Fl_Window *fl_find(WindowRef xid)

    -Return the Fl_Window that corresponds to the give window hande, or NULL if not found. FLTK Windows that are children of top-level windows share the WindowRef -with the top-level window. -

    Drawing Things Using QuickDraw

    -When the virtual function Fl_Widget::draw() is called, FLTK has prepared -the Window and CGrafPort for drawing. Clipping and offsets are prepared to allow -correct subwindow drawing. -

    -OS X doublebuffers all windows automatically. On OS X Fl_Window and -Fl_Double_Window are handled internally in the same way. -

    Mac File System Specifics

    -

    Resource Forks

    -FLTK does not access the resource fork of an application. However, a minimal -resource fork must be created for OS 8 and OS X applications. -

    Mac File Paths

    -FLTK uses Unix-style filenames and paths. - +

    WindowRef fl_xid(const Fl_Window *)

    + +

    Returns the window reference for an Fl_Window, or +NULL if the window has not been shown. + +

    Fl_Window *fl_find(WindowRef xid)

    + +

    Returns the Fl_Window that corresponds to the give +window handle, or NULL if not found. FLTK windows that +are children of top-level windows share the WindowRef of the +top-level window. + +

    Drawing Things Using QuickDraw

    + +

    When the virtual function Fl_Widget::draw() is +called, FLTK has prepared the Window and CGrafPort for drawing. +Clipping and offsets are prepared to allow correct subwindow +drawing. + +

    OS X doublebuffers all windows automatically. On OS X, +Fl_Window and Fl_Double_Window are handled +internally in the same way. + +

    Mac File System Specifics

    + +

    Resource Forks

    + +

    FLTK does not access the resource fork of an application. +However, a minimal resource fork must be created for OS 8 and OS +X applications. + +

    Mac File Paths

    + +

    FLTK uses UNIX-style filenames and paths. + +

    Known MacOS Bugs and Problems

    + +

    The following is a list of known bugs and problems in the MacOS +version of FLTK: + +

    + + + diff --git a/documentation/preface.html b/documentation/preface.html index c75012c47..ae8d2b2f1 100644 --- a/documentation/preface.html +++ b/documentation/preface.html @@ -10,11 +10,11 @@

    Preface

    This manual describes the Fast Light Tool Kit ("FLTK") -version 1.1.0, a C++ Graphical User Interface -("GUI") toolkit for UNIX, Microsoft Windows and MacOS. Each -of the chapters in this manual is designed as a tutorial for +version 1.1.0, a C++ Graphical User Interface +("GUI") toolkit for UNIX, Microsoft Windows and MacOS. Each +of the chapters in this manual is designed as a tutorial for using FLTK, while the appendices provide a convenient reference -for all FLTK widgets, functions, and operating system +for all FLTK widgets, functions, and operating system interfaces.

    Organization

    @@ -99,10 +99,11 @@ interfaces.

    distribution of FLTK is governed by the GNU Library General Public License, located in Appendix G.

    -

    UNIX is a registered trademark of the X Open Group, Inc. Microsoft -and Windows are registered trademarks of Microsoft Corporation. OpenGL -is a registered trademark of Silicon Graphics, Inc. . Apple, Macintosh, -MacOS and Mac OS X are registered trademarks of Apple Computer, Inc. .

    +

    UNIX is a registered trademark of the X Open Group, Inc. +Microsoft and Windows are registered trademarks of Microsoft +Corporation. OpenGL is a registered trademark of Silicon +Graphics, Inc. Apple, Macintosh, MacOS, and Mac OS X are +registered trademarks of Apple Computer, Inc.