"Final" changes for first draft of 1.0 documentation.

git-svn-id: file:///fltk/svn/fltk/trunk@187 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
author: Michael R Sweet <michael.r.sweet@gmail.com> 1999-01-07 16:36:11 +0000
committer: Michael R Sweet <michael.r.sweet@gmail.com> 1999-01-07 16:36:11 +0000
commit: 367f908d8ed5a3464b9676223a26ddf4e11bdb5b (patch)
tree: 2b0ec583852973ccf7b9804957e78d474e0e7e5d /documentation/osissues.html
parent: 85e6f449590eeb6e09f7547733adf4c7137470d0 (diff)
1 files changed, 275 insertions, 275 deletions
diff --git a/documentation/osissues.html b/documentation/osissues.html
index f9cd36991..3e651511e 100644
--- a/documentation/osissues.html
+++ b/documentation/osissues.html
@@ -1,184 +1,171 @@
 <HTML>
 <BODY>
 
-<H1 ALIGN=RIGHT>F - Operating System Specific Issues</H1
+<H1 ALIGN=RIGHT><A NAME="osissues">F - Operating System Issues</A></H1>
 
-</BODY>
-</HTML>
-<title>Fltk X-specific interface</title>
-<h2>Fltk X-specific interface</h2>
+This appendix describes the X and WIN32 specific interfaces in FLTK.
 
-<b>#include &lt;FL/x.H></b>
+<h2>X-Specific Interface</h2>
 
-<p>On Unix/X you can include this file to access fltk's X-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.
+<ul><pre>
+#include &lt;FL/x.H>
+</pre></ul>
 
-<p><hr>
+On X you can include this file to access FLTK's X-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.
 
-<h2>Handling other X events</h2>
+<h3>Handling Other X Events</h3>
 
-<a name=add_handler>
-</ul><h4><code>void Fl::add_handler(int (*f)(int));</code></h4><ul>
+<h4><a name="add_handler">void Fl::add_handler(int (*f)(int))</a></h4>
 
-Install a function to parse unrecognized events.  If fltk cannot figure
+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.
+returns non-zero then the event is ignored.
 
-<p>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 <a href=#fl_xevent><code>fl_xevent</code></a>.
+<p>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 <a href="#fl_xevent"><tt>fl_xevent</tt></a> variable.
 
 <p>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 instance FL_SHORTCUT).
+non-zero (for example <tt>FL_SHORTCUT</tt>).
 
-<a name=fl_xevent>
-</ul><h4><code>extern XEvent* fl_xvent;</code></h4><ul>
+<h4><a name="fl_xevent">extern XEvent *fl_xvent</a></h4>
 
-The most current X event.
+The most recent X event.
 
-<a name=fl_event_time>
-</ul><h4><code>extern ulong fl_event_time;</code></h4><ul>
+<h4><a name="fl_event_time">extern ulong fl_event_time</a></h4>
 
 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.
 
-</ul><h4><code>Window fl_xid(const Fl_Window*);</code></h4><ul>
+<h4><a name="fl_xid">Window fl_xid(const Fl_Window *)</a></h4>
 
-Returns the xid for a window, or zero if not shown().
+Returns the XID for a window, or zero if not <tt>shown()</tt>.
 
-</ul><h4><code>Fl_Window* fl_find(ulong xid);</code></h4><ul>
+<h4><a name="fl_find">Fl_Window *fl_find(ulong xid)</a></h4>
 
-<p>Return 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.
+Returns the <tt>Fl_Window</tt> that corresponds to the given XID, or
+<tt>NULL</tt> if not found.  This uses a cache so it is slightly faster
+than iterating through the windows yourself.
 
-</ul><h4><code>int fl_handle(const XEvent&);</code></h4><ul>
+<h4><a name="fl_handle">int fl_handle(const XEvent &amp;)</a></h4>
 
-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
+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 <tt>add_handler()</tt> functions all ignore it this returns
 false).
 
 <p>Besides feeding events your code should call <a
-href=Fl.html#flush>Fl::flush()</a> periodically so that fltk redraws
-it's windows.
+href="#flush"><tt>Fl::flush()</tt></a> periodically so that FLTK
+redraws its windows.
 
 <p>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=utilities.html#fl_ask>fl_ask()</a>, for
+window (by calling <a href="#fl_ask"><tt>fl_ask()</tt></a>, for
 instance) it will not return until the modal function returns.
 
-</ul>
-<p><hr>
+<h3>Drawing using Xlib</h3>
 
-<a name=draw>
-<h2>Drawing using Xlib</h2>
+The following global variables are set before
+<tt>Fl_Widget::draw()</tt> is called, or by <a
+href="#Fl_Window.make_current"><tt>Fl_Window::make_current()</tt></a>:
 
-</ul><h4><code>
-extern Display* fl_display;<br>
-extern Window fl_window;<br>
-extern GC fl_gc;<br>
-extern int fl_screen;<br>
-extern XVisualInfo* fl_visual;<br>
-extern Colormap fl_colormap;</code></h4><ul>
+<ul><pre>
+extern Display *fl_display;
+extern Window fl_window;
+extern GC fl_gc;
+extern int fl_screen;
+extern XVisualInfo *fl_visual;
+extern Colormap fl_colormap;
+</pre></ul>
 
-These global variables are set before Fl_Widget::draw() is called, or
-by <a href=Fl_Window.html#make_current>Fl_Window::make_current()</a>
 You must use them to produce Xlib calls.  Don't attempt to change
 them.  A typical X drawing call is written like this:
 
-<ul><p><code>XDrawSomething(fl_display, fl_window, fl_gc, ...);</code></ul>
+<ul><pre>
+XDrawSomething(fl_display, fl_window, fl_gc, ...);
+</pre></ul>
 
-<p>Other information such as the position or size of the X window can be
+Other information such as the position or size of the X window can be
 found by looking at <a
-href=Fl_Window.html#make_current><code>Fl_Window::current()</code></a>,
-which returns a pointer to the Fl_Window being drawn.
-
-</ul><h4><code>unsigned long fl_xpixel(Fl_Color i);</code></h4><ul>
+href="#Fl_Window.make_current"><tt>Fl_Window::current()</tt></a>, which
+returns a pointer to the <tt>Fl_Window</tt> being drawn.
 
-Returns the X pixel number used to draw the given fltk color index.
-This is the X pixel that <a href=Draw.html#fl_color>fl_color(i)</a> would use.
+<h4><a name="fl_xpixel">unsigned long fl_xpixel(Fl_Color i)<br>
+unsigned long fl_xpixel(uchar r, uchar g, uchar b)</a></h4>
 
-</ul><h4><code>unsigned long fl_xpixel(uchar r, uchar g, uchar
-b);</code></h4><ul>
+Returns the X pixel number used to draw the given FLTK color index or
+RGB color. This is the X pixel that <a
+href="#fl_color"><tt>fl_color()</tt></a> would use.
 
-Return the X pixel number used to draw the given rgb color.  This is
-the X pixel that <a href=Draw.html#fl_rgbcolor>fl_color(r,g,b)</a> would use.
-
-</ul><h4><code>extern XFontStruct* fl_xfont;</code></h4><ul>
+<h4><a name="fl_xfont">extern XFontStruct *fl_xfont</a></h4>
 
 Points at the font selected by the most recent <a
-href=Draw.html#fl_font>fl_font(font,size)</a>.  This is not
-necessarily the current font of fl_gc (that's not set until <a
-href=Draw.html#text>fl_draw(const char*,...)</a> is called).
-
-</ul>
+href="#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="#fl_draw"><tt>fl_draw()</tt></a> is called.
 
-<p><hr>
+<h3>Changing the Display, Screen, or X Visual</h3>
 
-<a name=visuals>
-<h2>Changing the display, screen, or X visual</h2>
+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="#visual">Fl::visual()</a>, which is a
+portable interface to get a full color and/or double buffered visual.
 
-<p>Fltk uses only a single display, screen, X visual, and X colormap.
-This greatly simplifies it's internal structure and makes it much
-smaller and faster.  You can change which it uses by setting global
-variables <i>before the first Fl_Window::show() is called</i>.
-You may also want to call <a
-href=Fl.html#visual>Fl::visual(int)</a>, which is a portable interface
-to get a full color and/or double buffered visual.
-
-</ul><h4><code>int Fl::display(const char *)</code></h4><ul>
+<h4><a name="display">int Fl::display(const char *)</a></h4>
 
 Set which X display to use.  This actually does
-<code>setenv("DISPLAY",&nbsp;x)</code> 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 on MSWindows, but
-it just sets the environment variable and has no other effect.
+<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 WIN32 but
+it has no effect.
 
-</ul><h4><code>extern Display* fl_display;</code></h4><ul>
+<h4><a name="fl_display">extern Display *fl_display</a></h4>
 
 The open X display.  This is needed as an argument to most Xlib calls.
-Don't attempt to change it!  This is zero before the display is opened.
+Don't attempt to change it!  This is <tt>NULL</tt> before the display is opened.
 
-</ul><h4><code>void fl_open_display();</code></h4><ul>
+<h4><a name="fl_open_display">void fl_open_display()</a></h4>
 
-Open the display.  Does nothing if it is already open.  This will make
-sure <code>fl_display</code> is non-zero.  You should call this if you
+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 show() of a window.
+before the first <tt>show()</tt> of a window.
 
-<p>This may call Fl::abort() if there is an error opening the display.
+<p>This may call <tt>Fl::abort()</tt> if there is an error opening the display.
 
-</ul><h4><code>void fl_close_display();</code></h4><ul>
+<h4><a name="fl_close_display">void fl_close_display()</a></h4>
 
 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
+You cannot open the display again, and probably cannot call any FLTK
 functions.
 
-</ul><h4><code>extern int fl_screen;</code></h4><ul>
+<h4><a name="fl_screen">extern int fl_screen</a></h4>
 
-Which screen 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: host:0,#.
+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,#".
 
-</ul><h4><code>extern XVisualInfo* fl_visual;<br>
-extern Colormap fl_colormap;</code></h4><ul>
+<h4><a name="fl_visual">extern XVisualInfo *fl_visual</a><br>
+<a name="fl_colormap">extern Colormap fl_colormap</a></h4>
 
-<p>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:
+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:
 
-<ul><code><pre>
+<ul><pre>
 Fl::args(argc, argv); // do this first so $DISPLAY is set
 fl_open_display();
 fl_visual = find_a_good_visual(fl_display, fl_screen);
@@ -186,50 +173,32 @@ 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);
-</pre></code></ul>
-
-</ul>
+</pre></ul>
 
-<p><hr>
-<a name=window>
-<h2>Using a subclass of Fl_Window for special X stuff</h2>
+<h3>Using a Subclass of Fl_Window for Special X Stuff</h3>
 
-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 calls only.
+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.
 
-<p>Fltk can also manage xid's provided by other libraries or programs,
+<p>FLTK can also manage XID's provided by other libraries or programs,
 and call those libraries when the window needs to be redrawn.
 
 <p>To do this, you need to make a subclass of <a
-href=Fl_Window.html>Fl_Window</a> and override some of these virtual
+href="#Fl_Window"><tt>Fl_Window</tt></a> and override some of these virtual
 functions:
 
-</ul><h4><code>virtual void Fl_Window::show()</code></h4><ul>
-
-<p>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():
-
-<h4><code>Fl_X* Fl_X::set_xid(Fl_Window*, Window xid);</code></h4><ul>
-
-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.
+<h4>virtual void Fl_Window::show()</h4>
 
-</ul><h4><code>void Fl_X::make_xid(Fl_Window*, XVisualInfo* =
-fl_visual, Colormap = fl_colormap);</code></h4><ul>
+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>.
 
-This static method does the most onerous parts of creating an X window,
-including setting the label, resize limitations, etc.  It then does
-set_xid with this new window and maps the window.
-
-</ul>
+<p>An example:
 
-<p>Example:
-
-<pre>
+<ul><pre>
 void MyWindow::show() {
   if (shown()) {Fl_Window::show(); return;}  // you must do this!
   fl_open_display();	// necessary if this is first window
@@ -243,47 +212,60 @@ void MyWindow::show() {
   }
   Fl_X::make_xid(this, visual, colormap);
 }
-</pre>
+</pre></ul>
+
+<h4>Fl_X *Fl_X::set_xid(Fl_Window *, Window xid)</h4>
+
+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.
+
+<h4>void Fl_X::make_xid(Fl_Window *, XVisualInfo *= fl_visual, Colormap = fl_colormap)</h4>
+
+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.
 
-</ul><h4><code>virtual void Fl_Window::flush()</code></h4><ul>
+<h4>virtual void Fl_Window::flush()</h4>
 
-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.
+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.
 
-<p>The X region that is a combination of all damage() calls done so
-far is in <code>Fl_X::i(this)->region</code>.  If null then
-you should redraw the entire window.  The undocumented function
-<code>fl_clip_region(XRegion)</code> will initialize the fl 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.
+<p>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> now owns it and
+will delete it when done.
 
-<p>If <code>damage()==2</code> then only X expose events have
-happened.  This may be useful if you have an undamaged image (such as
-a backing buffer) around.
+<p>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.
 
 <p>Here is a sample where an undamaged image is kept somewhere:
 
-<pre>
+<ul><pre>
 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 ...
 }
-</pre>
+</pre></ul>
 
-</ul><h4><code>virtual void Fl_Window::hide()</code></h4><ul>
+<h4>virtual void Fl_Window::hide()</h4>
 
-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:
+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:
 
-<pre>
+<ul><pre>
 void MyWindow::hide() {
   if (mypixmap) {
     XFreePixmap(fl_display,mypixmap);
@@ -291,165 +273,183 @@ void MyWindow::hide() {
   }
   Fl_Window::hide(); // you must call this
 }
-</pre>
+</pre></ul>
 
-</ul><h4><code>virtual void Fl_Window::~Fl_Window()</code></h4><ul>
+<h4>virtual void Fl_Window::~Fl_Window()</h4>
 
-Because of the way C++ works, if you override hide() you <i>must</i>
-override the destructor as well (otherwise only the base class hide()
+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):
 
-<pre>
+<ul><pre>
 MyWindow::~MyWindow() {
   hide();
 }
-</pre>
+</pre></ul>
 
-</ul>
+<h3>Setting the Icon of a Window</h3>
 
-<p><a href = index.html>(back to contents)</a>
-<title>Fltk MSWindows-specific interface</title>
-<h2>#include &lt;FL/x.H><br>
-Fltk MSWindows-specific interface</h2>
+FLTK currently supports setting a window's icon *before* it is shown using
+the <tt>Fl_Window::icon()</tt> method.
 
-The &lt;FL/x.H> header file defines the interface to fltk's
-MSWindows-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.
+<h4>void Fl_Window::icon(char *)</h4>
+
+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 the icon using a bitmap compiled with your application
+use:
+
+<ul><pre>
+#include "icon.xbm"
+
+Pixmap p = XCreatePixmapFromBitmapData(fl_display,
+               DefaultRootWindow(fl_display), icon_bits,
+	       icon_width, icon_height,
+	       BlackPixel(fl_display, DefaultScreen(fl_display)),
+	       WhitePixel(fl_display, DefaultScreen(fl_display)),
+	       DefaultDepth(fl_display, DefaultScreen(fl_display)))
+
+window->icon((char *)p);
+</ul></pre>
 
-<p><hr>
+<h2>WIN32-Specific Interface</h2>
 
-<h2>Handling other MSWindows messages</h2>
+<ul><pre>
+#include &lt;FL/x.H>
+</pre></ul>
 
-<p>A single WNDCLASSEX called "FLTK" is created.  All
-Fl_Windows are of this class.  This window class is created the first
-time Fl_Window::show() is called.
+The <tt>&lt;FL/x.H></tt> 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.
+
+<h3>Handling Other WIN32 Messages</h3>
+
+By default a single WNDCLASSEX called "FLTK" is created.  All
+<tt>Fl_Windows</tt> 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.
 
-<p>You can probably combine fltk with other libraries that make their
-own MSWindows window classes.  The easiest way is to call Fl::wait(), it
-will call DispatchMessage for all messages to the other windows.  If
+<p>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>, 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
-DispatchMessage()), but you will have to arrange for the function
-Fl::flush() to be called regularily (otherwise widgets will not
-update), and timeouts and the idle function will not work.
+<tt>DispatchMessage()</tt>), but you will have to arrange for the function
+<tt>Fl::flush()</tt> to be called regularily so that widgets are updated,
+timeouts are handled, and the idle functions are called.
 
-<a name=fl_msg>
-</ul><h4><code>extern MSG fl_msg;</code></h4><ul>
+<h4><a name="fl_msg">extern MSG fl_msg</a></h4>
 
-The most recent message read by GetMessage (which is called by
-<a href=Fl.html#wait>Fl::wait()</a>.  This may not be the most recent
-message sent to an fltk window, because silly MSWindows calls the
+The most recent message read by <tt>GetMessage</tt> (which is called by
+<a href="#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=add_handler>
-</ul><h4><code>void Fl::add_handler(int (*f)(int));</code></h4><ul>
+<h4><a name="WIN32.add_handler">void Fl::add_handler(int (*f)(int))</a></h4>
 
-Install a function to parse unrecognized messages sent to fltk
-windows.  If fltk cannot figure out what to do with a message, it
+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(...).
-
-</ul><h4><code>HWND fl_xid(const Fl_Window*);</code></h4><ul>
-
-Returns the window handle for a Fl_Window, or zero if not shown().
+all the handlers return zero then FLTK calls <tt>DefWindowProc()</tt>.
 
-</ul><h4><code>Fl_Window* fl_find(HWND xid)</code></h4><ul>
+<h4><a name="WIN32.fl_xid">HWND fl_xid(const Fl_Window *)</a></h4>
 
-<p>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.
+Returns the window handle for a <tt>Fl_Window</tt>, or zero if not
+<tt>shown()</tt>.
 
-</ul>
+<h4><a name="WIN32.fl_find">Fl_Window *fl_find(HWND xid)</a></h4>
 
-<p><hr>
+Return the <tt>Fl_Window</tt> that corresponds to the given window
+handle, or <tt>NULL</tt> if not found.  This uses a cache so it is
+slightly faster than iterating through the windows yourself.
 
-<a name=gdi>
-<h2>Drawing things using the MSWindows GDI</h2>
+<h3>Drawing Things Using the WIN32 GDI</h3>
 
-<p>When the virtual function Fl_Widget::draw() is called, fltk has
+When the virtual function <tt>Fl_Widget::draw()</tt> is called, FLTK has
 stashed in some global variables all the silly extra arguments you
 need to make a proper GDI call.  These are:
 
-</ul><h4><code>
-extern HINSTANCE fl_display;<br>
-extern HWND fl_window;<br>
-extern HDC fl_gc;<br>
-COLORREF fl_RGB();<br>
-HPEN fl_pen();<br>
-HBRUSH fl_brush();</code></h4><ul>
-
-These global variables are set before draw() is called, or by <a
-href=Fl_Window.html#make_current>Fl_Window::make_current()</a> You can
+<ul><pre>
+extern HINSTANCE fl_display;
+extern HWND fl_window;
+extern HDC fl_gc;
+COLORREF fl_RGB();
+HPEN fl_pen();
+HBRUSH fl_brush();
+</pre></ul>
+
+These global variables are set before <tt>draw()</tt> is called, or by <a
+href="#Fl_Window.make_current"><tt>Fl_Window::make_current()</tt></a>. You can
 refer to them when needed to produce GDI calls.  Don't attempt to
 change them.  The functions return GDI objects for the current color
-set by fl_color(), these are created as needed and cached.  A typical
+set by <tt>fl_color()</tt> and are created as needed and cached.  A typical
 GDI drawing call is written like this:
 
-<ul><p><code>DrawSomething(fl_gc, ..., fl_brush());</code></ul>
-
-<p>It may also be useful to refer to <a
-href=Fl_Window.html#make_current><code>Fl_Window::current()</code></a>
-to get the window's size or position.
-
-</ul>
-<p><hr>
-<h2>How to not get a MSDOS console window</h2>
+<ul><pre>
+DrawSomething(fl_gc, ..., fl_brush());
+</pre></ul>
 
-MSWindows has a really stupid mode switch stored in the executables that
-controls whether or not to make a console window (hint to Mr Gates:
-why not leave it hidden until the program prints something?).
+It may also be useful to refer to <a
+href="#Fl_Window.make_current"><tt>Fl_Window::current()</tt></a> to get
+the window's size or position.
 
-<p>To not produce a "console" window when you run your program add the
-following secret incantation to the Micro$oft linker:
+<h3>Setting the Icon of a Window</h3>
 
-<p><pre>        /SUBSYSTEM:WINDOWS /ENTRY:mainCRTStartup</pre>
+FLTK currently supports setting a window's icon *before* it is shown using
+the <tt>Fl_Window::icon()</tt> method.
 
-<p>Unfortunately this seems to completely disable stdin/stdout, even
-if you run the program from a console.  So don't do this until you
-have debugged your program!
+<h4>void Fl_Window::icon(char *)</h4>
 
-<p><hr>
-<h2>Other hints</h2>
+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:
 
-<p>I use capital C as the extension for c++ source code, for instace
-for Fluid output.  Unfortunately there is no way to convince VC++ to
-use this except to tell it to compile *everything* using C++ by
-putting the switch "/TP" in the options.  This makes it impossible to
-combine old C code and fltk code.
+<ul><pre>
+window->icon((char *)LoadIcon(fl_display, MAKEINTRESOURCE(IDI_ICON)));
+</ul></pre>
 
-<p><hr>
-<h2>Known bugs</h2>
+<h3>How to Not Get a MSDOS Console Window</h3>
 
-<p>If 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 MSWindows and probably
-impossible to get around.
+WIN32 has a really stupid mode switch stored in the executables that
+controls whether or not to make a console window.
 
-<p>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.
-
-<p>Cut text contains ^J rather than ^M^J to break lines.  This is a
-feature, not a bug.  
+<p>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).
 
-<p>I can't seem to get SetCapture (used by Fl::grab()) to work, and I
-can't find a way to stop the main window title from turning gray while
-menus are popped up.
+<p>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>
 
-<p>glpuzzle program does not animate unless you resize it first.  Unknown why.
+<p>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.
 
-<p>Fl_Window::fullscreen() not implemented (should take over the screen
-without a title bar).  Currently does maximize instead.
+<h3>Known Bugs</h3>
 
-<p>Import .bmp files into fluid. Wonko has the specs.
+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.  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.
 
-<p>Can't set icon of windows.
+<p><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.
 
+<p>Cut text contains ^J rather than ^M^J to break lines.  This is a
+feature, not a bug.  
 
+<p><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.
 
+<p>FLUID does not support BMP files yet.
 
+</BODY>
+</HTML>
author	Michael R Sweet <michael.r.sweet@gmail.com>	1999-01-07 16:36:11 +0000
committer	Michael R Sweet <michael.r.sweet@gmail.com>	1999-01-07 16:36:11 +0000
commit	367f908d8ed5a3464b9676223a26ddf4e11bdb5b (patch)
tree	2b0ec583852973ccf7b9804957e78d474e0e7e5d /documentation/osissues.html
parent	85e6f449590eeb6e09f7547733adf4c7137470d0 (diff)