Added Fl::first_window(window) to change which window is at the top of

the window list.  This window is used as the "parent" of any modal
windows you create so it is a good idea to be able to change it.
Normally it is whatever window got the last event.

Fixed Fl_Menu::global handler to use first_window so if a modal window
pops up in response it is parented to the window containing the
menubar rather than the current top window.  This was an annoying bug!

Copied fl_line_style() and the line_style demo over from fltk 2.0
because I am tired of mailing this code to people.  Better to advertise this
as "added fl_line_style() function to set line thickness, dash patterns,
and end caps".

Fixed the documentation for these changes.


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

3 files changed, 62 insertions, 17 deletions

diff --git a/documentation/Fl_Window.html b/documentation/Fl_Window.html
index 350a28c7c..87ac71072 100644
--- a/documentation/Fl_Window.html
+++ b/documentation/Fl_Window.html
@@ -49,32 +49,30 @@ exit(0)</TT> if this is the last top-level window. </P>
 </UL>
 </TD><TD align=left valign=top>
 <UL>
-<LI><A href=#Fl_Window.first_window>first_window</A></LI>
 <LI><A href=#Fl_Window.free_position>free_position</A></LI>
 <LI><A href=#Fl_Window.fullscreen>fullscreen</A></LI>
 <LI><A href=#Fl_Window.fullscreen_off>fullscreen_off</A></LI>
 <LI><A href=#Fl_Window.hide>hide</A></LI>
+<LI><A href=#Fl_Window.hotspot>hotspot</A></LI>
 </UL>
 </TD><TD align=left valign=top>
 <UL>
-<LI><A href=#Fl_Window.hotspot>hotspot</A></LI>
 <LI><A href=#Fl_Window.iconize>iconize</A></LI>
 <LI><A href=#Fl_Window.iconlabel>iconlabel</A></LI>
 <LI><A href=#Fl_Window.label>label</A></LI>
 <LI><A href=#Fl_Window.make_current>make_current</A></LI>
+<LI><A href=#Fl_Window.modal>modal</A></LI>
 </UL>
 </TD><TD align=left valign=top>
 <UL>
-<LI><A href=#Fl_Window.modal>modal</A></LI>
-<LI><A href=#Fl_Window.next_window>next_window</A></LI>
 <LI><A href=#Fl_Window.non_modal>non_modal</A></LI>
 <LI><A href=#Fl_Window.resize>resize</A></LI>
 <LI><A href=#Fl_Window.set_modal>set_modal</A></LI>
+<LI><A href=#Fl_Window.set_non_modal>set_non_modal</A></LI>
+<LI><A href=#Fl_Window.show>show</A></LI>
 </UL>
 </TD><TD align=left valign=top>
 <UL>
-<LI><A href=#Fl_Window.set_non_modal>set_non_modal</A></LI>
-<LI><A href=#Fl_Window.show>show</A></LI>
 <LI><A href=#Fl_Window.shown>shown</A></LI>
 <LI><A href=#Fl_Window.size_range>size_range</A></LI>
 <LI><A href=#Fl_Window.xclass>xclass</A></LI>
@@ -172,13 +170,7 @@ FL_SHOW</TT> events and <TT>visible()</TT> is turned on and off. </P>
 <P>There is no way to control what is drawn in the icon except with the 
 string passed to <TT>Fl_Window::xclass()</TT>.  You should not rely on 
 window managers displaying the icons. </P>
-<H4><A name=Fl_Window.first_window>Fl_Window *Fl::first_window()</A></H4>
- Returns the first <TT>shown()</TT> window in the widget hierarchy. If 
-no windows are displayed <TT>first_window</TT> returns <TT>NULL</TT>. 
-<H4><A name=Fl_Window.next_window>Fl_Window *Fl::next_window(const 
-Fl_Window*)</A></H4>
- Returns the next <TT>shown()</TT> window in the hierarchy.  You can 
-use this call to iterate through all the windows that are shown(). 
+
 <H4><A name=Fl_Window.resize>void Fl_Window::resize(int,int,int,int)</A></H4>
  Change the size and position of the window.  If <TT>shown()</TT> is 
 true, these changes are communicated to the window server (which may 
diff --git a/documentation/drawing.html b/documentation/drawing.html
index e29450c21..225806ee6 100644
--- a/documentation/drawing.html
+++ b/documentation/drawing.html
@@ -27,6 +27,7 @@ drawing functions:
 <UL>
 <LI><A href=#clipping>Clipping</A></LI>
 <LI><A href=#colors>Colors</A></LI>
+<LI><A href=#lines>Line dashes and thickness</A></LI>
 <LI><A href=#fast>Fast Shapes</A></LI>
 <LI><A href=#complex>Complex Shapes</A></LI>
 <LI><A href=#text>Text</A></LI>
@@ -82,6 +83,46 @@ for state save/restore.
 possible match to the RGB color is used.  The RGB color is used 
 directly on TrueColor displays. For colormap visuals the nearest index 
 in the gray ramp or color cube is used. 
+
+<h3><A name=lines>Line dashes and thickness</a></h3>
+
+<h4>void fl_line_style(int style, int width=0, char* dashes=0)</h4>
+
+Set how to draw lines (the "pen").  If you change this it is your
+responsibility to set it back to the default with
+<tt>fl_line_style(0)</tt>.
+
+<p><i>style</i> is a bitmask in which you 'or' the following values.  If
+you don't specify a dash type you will get a solid line.  If you don't
+specify a cap or join type you will get a system-defined default of
+whatever value is fastest.
+
+<ul>
+<li><tt>FL_SOLID&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -------</tt>
+<li><tt>FL_DASH&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - - - -</tt>
+<li><tt>FL_DOT&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; .......</tt>
+<li><tt>FL_DASHDOT&nbsp;&nbsp;&nbsp; - . - .</tt>
+<li><tt>FL_DASHDOTDOT - .. -</tt>
+<li><tt>FL_CAP_FLAT</tt>
+<li><tt>FL_CAP_ROUND</tt>
+<li><tt>FL_CAP_SQUARE</tt> (extends past end point 1/2 line width)
+<li><tt>FL_JOIN_MITER</tt> (pointed)
+<li><tt>FL_JOIN_ROUND</tt>
+<li><tt>FL_JOIN_BEVEL</tt> (flat)
+</ul>
+
+<p><i>width</i> is the number of pixels thick to draw the lines.  Zero
+results in the system-defined default, which on both X and Windows is
+somewhat different and nicer than 1.
+
+<p><i>dashes</i> is a pointer to an array of dash lengths, measured in
+pixels.  The first location is how long to draw a solid portion, the
+next is how long to draw the gap, then the solid, etc.  It is
+terminated with a zero-length entry.  A null pointer or a zero-length
+array results in a solid line.  Odd array sizes are not supported and
+result in undefined behavior.  <i>The dashes array does not work on
+Windows 95/98, use the dash styles instead.</i>
+
 <H3><A name=fast>Fast Shapes</A></H3>
  These are used to draw almost all the FLTK widgets.  They draw on 
 exact pixel boundaries and are as fast as possible, and their behavior 
diff --git a/documentation/functions.html b/documentation/functions.html
index c875420e8..638a3853b 100644
--- a/documentation/functions.html
+++ b/documentation/functions.html
@@ -478,8 +478,23 @@ only valid until the next event is processed.
 absolute position of an <TT>Fl_Window</TT> on the screen, use the 
 difference between <TT>event_x_root(),event_y_root()</TT> and <TT>
 event_x(),event_y()</TT>. 
+
 <H3><A name=first_window>static Fl_Window *Fl::first_window()</A></H3>
- Returns the first top-level window in the widget hierarchy. 
+Returns the first top-level window in the list of shown() windows.  If
+a modal() window is shown this is the top-most modal window, otherwise
+it is the most recent window to get an event.
+
+<H3><A name=next_window>static Fl_Window *Fl::next_window(Fl_Window *)</A></H3>
+Returns the next top-level window in the list of shown() windows.  You can 
+use this call to iterate through all the windows that are shown(). 
+
+<H3><A name=first_window>static void Fl::first_window(Fl_Window*)</A></H3>
+Sets the window that is returned by first_window.  The window is
+removed from wherever it is in the list and inserted at the top.  This
+is not done if Fl::modal() is on or if the window is not shown().
+Because the first window is used to set the "parent" of modal windows,
+this is often useful.
+
 <H3><A name=flush>static void Fl::flush()</A></H3>
  Causes all the windows that need it to be redrawn and graphics forced 
 out through the pipes.  This is what <TT>wait()</TT> does before 
@@ -591,9 +606,6 @@ windows <TT>shown()</TT>.
 The <TT>modal()</TT> window has its <TT>handle()</TT> method called 
 for all events, and no other windows will have <TT>handle()</TT>
 called (<A href=#grab><TT>grab()</TT></A> overrides this).
-<H3><A name=next_window>static Fl_Window *Fl::next_window(Fl_Window *)</A>
-</H3>
- Returns the next top-level window in the widget hierarchy. 
 <H3><A name=own_colormap>static void Fl::own_colormap()</A></H3>
  Makes FLTK use its own colormap.  This may make FLTK display better 
 and will reduce conflicts with other programs that want lots of colors.