now renaming restoring dir src_doc src.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6452 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

1 files changed, 765 insertions, 0 deletions

diff --git a/documentation/src/osissues.dox b/documentation/src/osissues.dox
new file mode 100644
index 000000000..b878d79d3
--- /dev/null
+++ b/documentation/src/osissues.dox
@@ -0,0 +1,765 @@
+/**
+
+ \page	osissues	F - Operating System Issues
+
+This appendix describes the operating system specific interfaces in FLTK.
+
+\section osissues_accessing Accessing the OS Interfaces
+
+All programs that need to access the operating system
+specific interfaces must include the following header file:
+
+\code
+#include <FL/x.H>
+\endcode
+
+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.
+
+<CENTER>
+<TABLE WIDTH="90%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
+<TR>
+	<TD><B>WARNING:</B>
+
+	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.
+
+	</TD>
+</TR>
+</TABLE>
+</CENTER>
+
+\section osissues_unit The UNIX (X11) Interface
+
+The UNIX interface provides access to the X Window System
+state information and data structures.
+
+\subsection osissues_x_events Handling Other X Events
+
+<A name="add_handler"></A> <!-- For old HTML links only ! -->
+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
+<A href="#fl_xevent"><tt>fl_xevent</tt></A> 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
+<tt>FL_SHORTCUT</tt>.
+
+<A name="fl_xevent"></A> <!-- For old HTML links only ! -->
+extern XEvent *fl_xvent
+
+This variable contains the most recent X event.
+
+<A name="fl_event_time"></A> <!-- For old HTML links only ! -->
+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.
+
+<A name="fl_xid"></A> <!-- For old HTML links only ! -->
+Window fl_xid(const Fl_Window *)
+
+Returns the XID for a window, or zero if not <tt>shown()</tt>.
+
+<A name="fl_find"></A> <!-- For old HTML links only ! -->
+Fl_Window *fl_find(ulong xid)
+
+Returns the <tt>Fl_Window</tt> that corresponds to the given
+XID, or <tt>NULL</tt> if not found. This function uses a cache
+so it is slightly faster than iterating through the windows
+yourself.
+
+<A name="fl_handle"></A> <!-- For old HTML links only ! -->
+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 <tt>add_handler()</tt>
+functions all return 0, this function will return false.
+
+Besides feeding events your code should call
+<A href="Fl.html#Fl.flush"><tt>Fl::flush()</tt></A>
+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
+<A href="functions.html#fl_ask"><tt>fl_ask()</tt></A>,
+for instance, it will not return until the modal function
+returns.
+
+\subsection osissues_drawing_xlib Drawing using Xlib
+
+The following global variables are set before
+<A HREF="subclassing.html#draw"><tt>Fl_Widget::draw()</tt></A>
+is called, or by
+<A href="Fl_Window.html#Fl_Window.make_current"><tt>Fl_Window::make_current()</tt></A>:
+
+\code
+extern Display *fl_display;
+extern Window fl_window;
+extern GC fl_gc;
+extern int fl_screen;
+extern XVisualInfo *fl_visual;
+extern Colormap fl_colormap;
+\endcode
+
+You must use them to produce Xlib calls.  Don't attempt to change
+them. A typical X drawing call is written like this:
+
+\code
+XDrawSomething(fl_display, fl_window, fl_gc, ...);
+\endcode
+
+Other information such as the position or size of the X
+window can be found by looking at
+<A href="Fl_Window.html#Fl_Window.make_current"><tt>Fl_Window::current()</tt></A>,
+which returns a pointer to the <tt>Fl_Window</tt> being drawn.
+
+<A name="fl_xpixel"></A> <!-- For old HTML links only ! -->
+unsigned long fl_xpixel(Fl_Color i) <br>
+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
+<A href="drawing.html#fl_color"><tt>fl_color()</tt></A> would use.
+
+<A name="fl_parse_color"></A> <!-- For old HTML links only ! -->
+int fl_parse_color(const char* p, uchar& r, uchar& g, uchar& b)
+
+Convert a name into the red, green, and blue values of a color
+by parsing the X11 color names. On other systems, <tt>fl_parse_color</tt>
+can only convert names in hexadecimal encoding, for example <tt>\#ff8083</tt>.
+ 
+<A name="fl_xfont"></A> <!-- For old HTML links only ! -->
+extern XFontStruct *fl_xfont
+
+Points to the font selected by the most recent
+<A href="drawing.html#fl_font"><tt>fl_font()</tt></A>.
+This is not necessarily the current font of <tt>fl_gc</tt>,
+which is not set until
+<A href="drawing.html#text"><tt>fl_draw()</tt></A>
+is called. If FLTK was compiled with Xft support, <tt>fl_xfont</tt>
+will usually be 0 and <tt>fl_xftfont</tt> will contain a pointer 
+to the XftFont structure instead.
+
+<A name="fl_xftfont"></A> <!-- For old HTML links only ! -->
+extern void *fl_xftfont
+
+If FLTK was compiled with Xft support enabled, <tt>fl_xftfont</tt>
+Points to the xft font selected by the most recent
+<A href="drawing.html#fl_font"><tt>fl_font()</tt></A>.
+Otherwise it will be 0. <tt>fl_xftfont</tt> should be cast to 
+<tt>XftFont*</tt>.
+
+\subsection osissues_xvisual 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 <I>before the first
+<tt>Fl_Window::show()</tt> is called</I>. You may also want to call
+<A href="Fl.html#Fl.visual">Fl::visual()</A>,
+which is a portable interface to get a full color and/or double buffered
+visual.
+
+<A name="display"></A> <!-- For old HTML links only ! -->
+int Fl::display(const char *)
+
+Set which X display to use.  This actually does
+<tt>putenv("DISPLAY=...")</tt> so that child programs
+will display on the same screen if called with <tt>exec()</tt>.
+This must be done before the display is opened. This call is
+provided under MacOS and WIN32 but it has no effect.
+
+<A name="fl_display"></A> <!-- For old HTML links only ! -->
+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 <tt>NULL</tt>
+before the display is opened.
+
+<A name="fl_open_display"></A> <!-- For old HTML links only ! -->
+void fl_open_display()
+
+Opens the display. Does nothing if it is already open. This
+will make sure <tt>fl_display</tt> 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 <tt>show()</tt> of a
+window.
+
+This may call <tt>Fl::abort()</tt> if there is an error
+opening the display.
+
+<A name="fl_close_display"></A> <!-- For old HTML links only ! -->
+void fl_close_display()
+
+This closes the X connection. You do <I>not</I> 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.
+
+<A name="fl_screen"></A> <!-- For old HTML links only ! -->
+extern int fl_screen
+
+Which screen number to use. This is set by
+<tt>fl_open_display()</tt> 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
+<tt>Fl::display()</tt> string to "host:0.#".
+
+<A name="fl_visual"></A> <!-- For old HTML links only ! -->
+extern XVisualInfo *fl_visual <br>
+<A name="fl_colormap"></A> <!-- For old HTML links only ! -->
+extern Colormap fl_colormap
+
+The visual and colormap that FLTK will use for all windows.
+These are set by <tt>fl_open_display()</tt> to the default
+visual and colormap. You can change them before calling
+<tt>show()</tt> on the first window. Typical code for changing
+the default visual is:
+
+\code
+Fl::args(argc, argv); // do this first so $DISPLAY is set
+fl_open_display();
+fl_visual = find_a_good_visual(fl_display, fl_screen);
+if (!fl_visual) Fl::abort("No good visual");
+fl_colormap = make_a_colormap(fl_display, fl_visual->visual, fl_visual->depth);
+// it is now ok to show() windows:
+window->show(argc, argv);
+\endcode
+
+\subsection osissues_specialx 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 <tt>draw()</tt> 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
+<A href="Fl_Window.html#Fl_Window"><tt>Fl_Window</tt></A>
+and override some of these virtual functions:
+
+virtual void Fl_Window::show()
+
+If the window is already <tt>shown()</tt> this must cause it
+to be raised, this can usually be done by calling
+<tt>Fl_Window::show()</tt>. If not <tt>shown()</tt> your
+implementation must call either <tt>Fl_X::set_xid()</tt> or
+<tt>Fl_X::make_xid()</tt>.
+
+An example:
+
+\code
+void MyWindow::show() {
+  if (shown()) {Fl_Window::show(); return;}  // you must do this!
+  fl_open_display();	// necessary if this is first window
+  // we only calcualte the necessary visual colormap once:
+  static XVisualInfo *visual;
+  static Colormap colormap;
+  if (!visual) {
+    visual = figure_out_visual();
+    colormap = XCreateColormap(fl_display, RootWindow(fl_display,fl_screen),
+                               vis->visual, AllocNone);
+  }
+  Fl_X::make_xid(this, visual, colormap);
+}
+\endcode
+
+Fl_X *Fl_X::set_xid(Fl_Window *, Window xid)
+
+Allocate a hidden structure called an <tt>Fl_X</tt>, put the
+XID into it, and set a pointer to it from the
+<tt>Fl_Window</tt>. This causes <tt>Fl_Window::shown()</tt> 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 <tt>Fl_X::set_xid()</tt> with this new window and
+maps the window.
+
+virtual void Fl_Window::flush()
+
+This virtual function is called by <tt>Fl::flush()</tt> to
+update the window. For FLTK's own windows it does this by
+setting the global variables <tt>fl_window</tt> and
+<tt>fl_gc</tt> and then calling the <tt>draw()</tt> 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 <tt>damage()</tt>
+calls done so far is in <tt>Fl_X::i(this)->region</tt>. If
+<tt>NULL</tt> then you should redraw the entire window. The
+undocumented function <tt>fl_clip_region(XRegion)</tt> will
+initialize the FLTK clip stack with a region or <tt>NULL</tt>
+for no clipping. You must set region to <tt>NULL</tt> afterwards
+as <tt>fl_clip_region()</tt> will own and delete it when
+done.
+
+If <tt>damage() & FL_DAMAGE_EXPOSE</tt> 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:
+
+\code
+void MyWindow::flush() {
+  fl_clip_region(Fl_X::i(this)->region);
+  Fl_X::i(this)->region = 0;
+  if (damage() != 2) {... draw things into backing store ...}
+  ... copy backing store to window ...
+}
+\endcode
+
+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 <tt>Fl_Window::hide()</tt> to get rid of
+the main window identified by <tt>xid()</tt>. If you override
+this, you must also override the destructor as shown:
+
+\code
+void MyWindow::hide() {
+  if (mypixmap) {
+    XFreePixmap(fl_display,mypixmap);
+    mypixmap = 0;
+  }
+  Fl_Window::hide(); // you must call this
+}
+\endcode
+
+virtual void Fl_Window::~Fl_Window()
+
+Because of the way C++ works, if you override <tt>hide()</tt>
+you <I>must</I> override the destructor as well (otherwise only
+the base class <tt>hide()</tt> is called):
+
+\code
+MyWindow::~MyWindow() {
+  hide();
+}
+\endcode
+
+\subsection osissues_x_icon Setting the Icon of a Window
+
+FLTK currently supports setting a window's icon <b>before</b> it
+is shown using the <tt>Fl_Window::icon()</tt> method.
+
+void Fl_Window::icon(char *)
+
+Sets the icon for the window to the passed pointer. You will
+need to cast the icon <tt>Pixmap</tt> to a <tt>char *</tt> when
+calling this method. To set a monochrome icon using a bitmap compiled
+with your application use:
+
+\code
+#include "icon.xbm"
+
+fl_open_display(); // needed if display has not been previously opened
+
+Pixmap p = XCreateBitmapFromData(fl_display, DefaultRootWindow(fl_display),
+                                 icon_bits, icon_width, icon_height);
+
+window->icon((char *)p);
+\endcode
+
+To use a multi-colored icon, the XPM format and library
+should be used as follows:
+
+\code
+#include <X11/xpm.h>
+#include "icon.xpm"
+
+fl_open_display();                // needed if display has not been previously opened
+
+Pixmap p, mask;
+
+XpmCreatePixmapFromData(fl_display, DefaultRootWindow(fl_display),
+                                 icon_xpm, &p, &mask, NULL);
+
+window->icon((char *)p);
+\endcode
+
+When using the Xpm library, be sure to include it in the list
+of libraries that are used to link the application (usually "-lXpm").
+
+<CENTER>
+<TABLE WIDTH="90%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
+<TR>
+	<TD><B>NOTE:</B>
+	
+	You must call <A
+	HREF="Fl_Window.html#Fl_Window.show"><tt>Fl_Window::show(argc,
+	argv)</tt></A> for the icon to be used. The
+	<tt>Fl_Window::show()</tt> method does not bind the icon
+	to the window.
+
+	</TD>
+</TR>
+</TABLE>
+</CENTER>
+
+\subsection osissues_xresources X Resources
+
+When the
+<A HREF="Fl_Window.html#Fl_Window.show"><tt>Fl_Window::show(argc, argv)</tt></A>
+method is called, FLTK looks for the following X resources:
+
+\li <tt>background</tt> - The default background color
+	for widgets (color).
+
+\li <tt>dndTextOps</tt> - The default setting for
+	drag and drop text operations (boolean).
+
+\li <tt>foreground</tt> - The default foreground (label)
+	color for widgets (color).
+
+\li <tt>scheme</tt> - The default scheme to use (string).
+
+\li <tt>selectBackground</tt> - The default selection
+	color for menus, etc. (color).
+
+\li <tt>Text.background</tt> - The default background
+	color for text fields (color).
+
+\li <tt>tooltips</tt> - The default setting for
+	tooltips (boolean).
+
+\li <tt>visibleFocus</tt> - The default setting for
+	visible keyboard focus on non-text widgets (boolean).
+
+Resources associated with the first window's
+<A HREF="Fl_Window.html#Fl_Window.xclass"><tt>Fl_Window::xclass()</tt></A>
+string are queried first, or if no class has been specified then
+the class "fltk" is used (e.g. <tt>fltk.background</tt>). If no
+match is found, a global search is done (e.g.
+<tt>*background</tt>).
+
+\section osissues_win32 The Windows (WIN32) Interface
+
+The Windows interface provides access to the WIN32 GDI
+state information and data structures.
+
+\subsection osissues_win32_messages Handling Other WIN32 Messages
+
+By default a single WNDCLASSEX called "FLTK" is
+created. All <tt>Fl_Window</tt>'s are of this class unless you
+use <tt>Fl_Window::xclass()</tt>. The window class is created
+the first time <tt>Fl_Window::show()</tt> is called.
+
+You can probably combine FLTK with other libraries that make
+their own WIN32 window classes. The easiest way is to call
+<tt>Fl::wait()</tt>, as it will call <tt>DispatchMessage</tt>
+for all messages to the other windows. If necessary you can let
+the other library take over as long as it calls
+<tt>DispatchMessage()</tt>, but you will have to arrange for the
+function <tt>Fl::flush()</tt> to be called regularly so that
+widgets are updated, timeouts are handled, and the idle
+functions are called.
+
+<A name="fl_msg"></A> <!-- For old HTML links only ! -->
+extern MSG fl_msg
+
+This variable contains the most recent message read by
+<tt>GetMessage</tt>, which is called by <A
+href="Fl.html#Fl.wait"><tt>Fl::wait()</tt></A>. 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).
+
+<A name="WIN32.add_handler"></A> <!-- For old HTML links only ! -->
+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 <tt>DefWindowProc()</tt>.
+
+<A name="WIN32.fl_xid"></A> <!-- For old HTML links only ! -->
+HWND fl_xid(const Fl_Window *)
+
+Returns the window handle for a <tt>Fl_Window</tt>, or zero
+if not <tt>shown()</tt>.
+
+<A name="WIN32.fl_find"></A> <!-- For old HTML links only ! -->
+Fl_Window *fl_find(HWND xid)
+
+Returns the <tt>Fl_Window</tt> that corresponds to the given
+window handle, or <tt>NULL</tt> if not found. This function uses
+a cache so it is slightly faster than iterating through the
+windows yourself.
+
+<A name="WIN32.gdi"></A> <!-- For old HTML links only ! -->
+\subsection osissues_win32_gdi Drawing Things Using the WIN32 GDI
+
+When the virtual function
+<A HREF="subclassing.html#draw"><tt>Fl_Widget::draw()</tt></A> is
+called, FLTK stores all the silly extra arguments you need to
+make a proper GDI call in some global variables:
+
+\code
+extern HINSTANCE fl_display;
+extern HWND fl_window;
+extern HDC fl_gc;
+COLORREF fl_RGB();
+HPEN fl_pen();
+HBRUSH fl_brush();
+\endcode
+
+These global variables are set before <tt>draw()</tt> is called, or by
+<A href="Fl_Window.html#Fl_Window.make_current"><tt>Fl_Window::make_current()</tt></A>.
+You can refer to them when needed to produce GDI calls, but don't
+attempt to change them. The functions return GDI objects for
+the current color set by <tt>fl_color()</tt> and are created as
+needed and cached. A typical GDI drawing call is written like
+this:
+
+\code
+DrawSomething(fl_gc, ..., fl_brush());
+\endcode
+
+It may also be useful to refer to
+<A href="Fl_Window.html#Fl_Window.make_current"><tt>Fl_Window::current()</tt></A>
+to get the window's size or position.
+
+\subsection osissues_icon_windows Setting the Icon of a Window
+
+FLTK currently supports setting a window's icon *before* it
+is shown using the <tt>Fl_Window::icon()</tt> method.
+
+void Fl_Window::icon(char *)
+
+Sets the icon for the window to the passed pointer. You will
+need to cast the <tt>HICON</tt> handle to a <tt>char *</tt> when
+calling this method. To set the icon using an icon resource
+compiled with your application use:
+
+\code
+window->icon((char *)LoadIcon(fl_display, MAKEINTRESOURCE(IDI_ICON)));
+\endcode
+
+You can also use the <tt>LoadImage()</tt> and related
+functions to load specific resolutions or create the icon from
+bitmap data.
+
+<CENTER>
+<TABLE WIDTH="90%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
+<TR>
+	<TD><B>NOTE:</B>
+	
+	You must call <A
+	HREF="Fl_Window.html#Fl_Window.show"><tt>Fl_Window::show(argc,
+	argv)</tt></A> for the icon to be used. The
+	<tt>Fl_Window::show()</tt> method does not bind the icon
+	to the window.
+
+	</TD>
+</TR>
+</TABLE>
+</CENTER>
+
+\subsection osissues_msdos_console 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.
+
+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 <tt>WinMain()</tt> function that calls the
+ANSI standard <tt>main()</tt> entry point for you. <I>This
+function creates a console window when you use the debug version
+of the library.</I>
+
+WIN32 applications without a console cannot write to
+<tt>stdout</tt> or <tt>stderr</tt>, 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.
+
+\subsection osissues_win32_problems Known WIN32 Bugs and Problems
+
+The following is a list of known bugs and problems in the WIN32
+version of FLTK:
+
+\li	If a program is deactivated, <tt>Fl::wait()</tt>
+	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. We were
+	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.
+
+\li	<tt>Fl_Gl_Window::can_do_overlay()</tt> returns true
+	until the first time it attempts to draw an overlay, and
+	then correctly returns whether or not there is overlay
+	hardware.
+
+\li	<tt>SetCapture</tt> (used by <tt>Fl::grab()</tt>)
+	doesn't work, and the main window title bar turns gray
+	while menus are popped up.
+
+\li	Compilation with <tt>gcc 3.4.4</tt> and <tt>-Os</tt> exposes an
+	optimisation bug in gcc. The symptom is that when drawing
+	filled circles only the perimeter is drawn. This can for instance
+	be seen in the symbols demo. Other optimisation options such
+	as -O2 and -O3 seem to work OK. More details can be found
+	in STR#1656
+
+\section osissues_macos The MacOS Interface
+
+FLTK supports MacOS X using the Apple Carbon library. Older
+versions of MacOS are <I>not</I> supported.
+
+\par Control, Option, and Command Modifier Keys
+
+FLTK maps the Mac 'control' key to <tt>FL_CTRL</tt>, the
+'option' key to <tt>FL_ALT</tt> and the 'Apple' key to
+<tt>FL_META</tt>. Keyboard events return the key name in
+<tt>Fl::event_key()</tt> and the keystroke translation in
+<tt>Fl::event_text()</tt>. For example, typing Option-Y on a Mac
+keyboard will set <tt>FL_ALT</tt> in <tt>Fl::event_state()</tt>,
+set <tt>Fl::event_key()</tt> to 'y' and return the Yen symbol in
+<tt>Fl::event_text()</tt>.
+
+WindowRef fl_xid(const Fl_Window *)
+
+Returns the window reference for an <tt>Fl_Window</tt>, or
+<tt>NULL</tt> if the window has not been shown.
+
+Fl_Window *fl_find(WindowRef xid)
+
+Returns the <tt>Fl_Window</tt> that corresponds to the give
+window handle, or <tt>NULL</tt> if not found. FLTK windows that
+are children of top-level windows share the WindowRef of the
+top-level window.
+
+\subsection osissues_apple_quit Apple "Quit" Event
+
+When the user press Cmd-Q or requests a termination of the
+application, OS X will send a "Quit" Apple Event. FLTK handles
+this event by sending an <tt>FL_CLOSE</tt> event to all open
+windows. If all windows close, the application will terminate.
+
+\subsection osissues_apple_open Apple "Open" Event
+
+Whenever the user drops a file onto an application icon, OS X
+generates an Apple Event of the type "Open". You can have FLTK
+notify you of an Open event by setting the <tt>fl_open_callback</tt>.
+
+<a name="fl_open_callback"></A> <!-- For old HTML links only ! -->
+void fl_open_callback(void (*cb)(const char *))
+
+<tt>cb</tt> will be called with a single iUnix-style file name and path.
+If multiple files were dropped, <tt>fl_open_callback</tt> will be called
+multiple times.
+
+\subsection osissues_quickdraw Drawing Things Using QuickDraw
+
+When the virtual function <tt>Fl_Widget::draw()</tt> is
+called, FLTK has prepared the Window and CGrafPort for drawing.
+Clipping and offsets are prepared to allow correct subwindow
+drawing.
+
+\subsection osissues_quartz Drawing Things Using Quartz
+
+If the FLTK library was compiled using the configuration
+flag <tt>--enable-quartz</tt>, all code inside <tt>Fl_Widget::draw()</tt>
+is expected to call Quartz drawing functions instead of 
+QuickDraw. The Quartz coordinate system is flipped to match
+FLTK's coordinate system. The origin for all drawing is in the top
+left corner of the enclosing <tt>Fl_Window</tt>.
+
+Fl_Double_Window
+
+OS X double-buffers all windows automatically. On OS X,
+<tt>Fl_Window</tt> and <tt>Fl_Double_Window</tt> are handled
+internally in the same way.
+
+\subsection osissues_mac_files Mac File System Specifics
+
+\par Resource Forks
+
+FLTK does not access the resource fork of an application.
+However, a minimal resource fork must be created for OS X
+applications
+
+<CENTER>
+<TABLE WIDTH="80%" BORDER="1" BGCOLOR="#cccccc" CELLPADDING="5">
+<TR><TD><B>Caution:</B>
+
+When using UNIX commands to copy or move executables, OS X
+will NOT copy any resource forks! For copying and moving use
+CpMac and MvMac respectively. For creating a tar archive, all
+executables need to be stripped from their Resource Fork before
+packing, e.g. "DeRez fluid > fluid.r". After unpacking the
+Resource Fork needs to be reattached, e.g. "Rez fluid.r -o
+fluid".
+</TD></TR></TABLE>
+</CENTER>
+
+It is advisable to use the Finder for moving and copying and
+Mac archiving tools like Sit for distribution as they will
+handle the Resource Fork correctly. 
+
+\par Mac File Paths
+
+FLTK uses UNIX-style filenames and paths.
+
+\subsection osissues_macos_problems Known MacOS Bugs and Problems
+
+The following is a list of known bugs and problems in the
+MacOS version of FLTK:
+
+\li	Line styles are not well supported. This is due to
+	limitations in the QuickDraw interface.
+
+\li	Nested subwindows are not supported, i.e. you can
+	have a <tt>Fl_Window</tt> widget inside a
+	<tt>Fl_Window</tt>, but not a <tt>Fl_Window</tt> inside a
+	<tt>Fl_Window</tt> inside a <tt>Fl_Window</tt>.
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="forms.html">[Previous]</a>&nbsp;
+     \ref forms &nbsp;&nbsp;
+<a class="el" href="migration_1_1.html">[Next]</a>&nbsp;
+     \ref migration_1_1
+
+\endhtmlonly
+*/