Merge remote-tracking branch 'upstream/master'

8 files changed, 244 insertions, 50 deletions

diff --git a/CMake/options.cmake b/CMake/options.cmake
index bc3aa7e69..c747484bd 100644
--- a/CMake/options.cmake
+++ b/CMake/options.cmake
@@ -142,6 +142,10 @@ option(OPTION_FILESYSTEM_SUPPORT "allow file system support" ON)
 if(DOXYGEN_FOUND)
     option(OPTION_BUILD_HTML_DOCUMENTATION "build html docs" OFF)
     option(OPTION_INSTALL_HTML_DOCUMENTATION "install html docs" OFF)
+
+    option(OPTION_INCLUDE_DRIVER_DOCUMENTATION "include driver (developer) docs" OFF)
+    mark_as_advanced(OPTION_INCLUDE_DRIVER_DOCUMENTATION)
+
     if(LATEX_FOUND)
       option(OPTION_BUILD_PDF_DOCUMENTATION "build pdf docs" OFF)
       option(OPTION_INSTALL_PDF_DOCUMENTATION "install pdf docs" OFF)
diff --git a/FL/Fl_Sys_Menu_Bar.H b/FL/Fl_Sys_Menu_Bar.H
index 551ebc387..ecf72ff15 100644
--- a/FL/Fl_Sys_Menu_Bar.H
+++ b/FL/Fl_Sys_Menu_Bar.H
@@ -16,6 +16,11 @@
 //     http://www.fltk.org/str.php
 //
 
+/** \file
+ Definition of class Fl_Sys_Menu_Bar.
+ */
+
+
 #ifndef Fl_Sys_Menu_Bar_H
 #define Fl_Sys_Menu_Bar_H
 
@@ -44,7 +49,8 @@ class Fl_Sys_Menu_Bar_Driver;
  Changes to the menu state are immediately visible in the menubar when they are made
  using member functions of the Fl_Sys_Menu_Bar class. Other changes (e.g., by a call to
  Fl_Menu_Item::set()) should be followed by a call to update() to be
- visible in the menubar across all platforms.
+ visible in the menubar across all platforms. Global variable \ref fl_sys_menu_bar points to
+ the unique, current system menu bar.
  
  A few FLTK menu features are not supported by the Mac System menu:
   \li no symbolic labels
@@ -102,6 +108,8 @@ public:
   static void create_window_menu();
 };
 
+/** The system menu bar.
+ */
 extern Fl_Sys_Menu_Bar *fl_sys_menu_bar;
 
 #endif // Fl_Sys_Menu_Bar_H
diff --git a/FL/mac.H b/FL/mac.H
index 6acb0900d..7e4f345ff 100644
--- a/FL/mac.H
+++ b/FL/mac.H
@@ -135,10 +135,6 @@ void fl_mac_set_about(Fl_Callback *cb, void *user_data, int shortcut = 0);
  */
 extern int fl_mac_os_version;
 
-/** The system menu bar.
- */
-//extern class Fl_Sys_Menu_Bar *fl_sys_menu_bar;
-
 struct Fl_Menu_Item;
 
 class Fl_Mac_App_Menu {
diff --git a/README.CMake.txt b/README.CMake.txt
index 142603dad..88c48d679 100644
--- a/README.CMake.txt
+++ b/README.CMake.txt
@@ -103,11 +103,11 @@ OPTION_ARCHFLAGS - default EMPTY
    Extra architecture flags.
 
 OPTION_APPLE_X11 - default OFF
-   In case you want to use X11 on OSX.
+   In case you want to use X11 on macOS.
    Use this only if you know what you do, and if you have installed X11.
 
 OPTION_USE_POLL - default OFF
-   Don't use this one either.
+   Don't use this one either, it is deprecated.
 
 OPTION_BUILD_SHARED_LIBS - default OFF
    Normally FLTK is built as static libraries which makes more portable
@@ -117,10 +117,10 @@ OPTION_BUILD_EXAMPLES - default ON
    Builds the many fine example programs.
 
 OPTION_CAIRO - default OFF
-   Enables libcairo support - see README.CMake.txt.
+   Enables libcairo support - see README.Cairo.txt.
 
 OPTION_CAIROEXT - default OFF
-   Enables extended libcairo support - see README.CMake.txt.
+   Enables extended libcairo support - see README.Cairo.txt.
 
 OPTION_USE_GL - default ON
    Enables OpenGL support.
@@ -169,6 +169,28 @@ OPTION_PRINT_SUPPORT - default ON
    is somewhat smaller. This option makes sense only on the Unix/Linux
    platform or when OPTION_APPLE_X11 is ON.
 
+
+Documentation options: these options are only available if `doxygen' is
+   installed and found by CMake. PDF related options require also `latex'.
+
+OPTION_BUILD_HTML_DOCUMENTATION - default OFF
+OPTION_BUILD_PDF_DOCUMENTATION - default OFF
+   These options can be used to switch HTML documentation generation with
+   doxygen on. The build targets ('html', 'pdf', or 'docs') need still to
+   be executed explicitly.
+
+OPTION_INCLUDE_DRIVER_DOCUMENTATION - default OFF
+   This option adds driver documentation to HTML and PDF docs (if ON). This
+   option is marked as "advanced" since it is only useful for FLTK developers
+   or advanced users.
+
+OPTION_INSTALL_HTML_DOCUMENTATION - default OFF
+OPTION_INSTALL_PDF_DOCUMENTATION - default OFF
+   If these options are ON then the HTML and/or PDF docs get installed
+   when the 'install' target is executed, e.g. with `make install'. You
+   need to select above options OPTION_BUILD_*_DOCUMENTATION as well.
+
+
  2.3  Building under Linux with Unix Makefiles
 -----------------------------------------------
 
@@ -543,3 +565,4 @@ Apr 07 2015 - AlbrechtS: update use example and more docs
 Jan 31 2016 - msurette: custom command instead of fltk_wrap_ui
 Nov 01 2016 - AlbrechtS: remove deprecated FLTK_USE_FILE, add MinGW build
 Jul 05 2017 - matt: added instructions for MacOS and Xcode
+Dec 29 2018 - AlbrechtS: add documentation option descriptions
diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt
index 720af95d3..cec1f5104 100644
--- a/documentation/CMakeLists.txt
+++ b/documentation/CMakeLists.txt
@@ -18,6 +18,14 @@
 
 set (DOCS)
 
+set (FL_VERSION "${FLTK_VERSION_FULL}")
+
+if (OPTION_INCLUDE_DRIVER_DOCUMENTATION)
+  set (DRIVER_DOCS "DriverDev")
+else ()
+  set (DRIVER_DOCS "")
+endif ()
+
 #--------------------------
 # build html documentation
 #--------------------------
@@ -31,7 +39,6 @@ if(OPTION_BUILD_HTML_DOCUMENTATION)
     set(GENERATE_HTML	YES)
     set(GENERATE_LATEX	NO)
     set(LATEX_HEADER	"")
-    set(FL_VERSION	"${FLTK_VERSION_FULL}")
 
     configure_file(
 	${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
@@ -64,7 +71,6 @@ if (OPTION_BUILD_PDF_DOCUMENTATION)
     set(GENERATE_HTML	NO)
     set(GENERATE_LATEX	YES)
     set(LATEX_HEADER	"${CMAKE_CURRENT_BINARY_DIR}/fltk-book.tex")
-    set(FL_VERSION	"${FLTK_VERSION_FULL}")
 
     configure_file(
 	${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
diff --git a/documentation/Doxyfile.in b/documentation/Doxyfile.in
index d5a7a7681..58bc2b67f 100644
--- a/documentation/Doxyfile.in
+++ b/documentation/Doxyfile.in
@@ -437,8 +437,7 @@ GENERATE_DEPRECATEDLIST= YES
 # The ENABLED_SECTIONS tag can be used to enable conditional
 # documentation sections, marked by \if sectionname ... \endif.
 
-ENABLED_SECTIONS       = 
-# ENABLED_SECTIONS       += DriverDev
+ENABLED_SECTIONS       = @DRIVER_DOCS@
 
 # The MAX_INITIALIZER_LINES tag determines the maximum number of lines
 # the initial value of a variable or define consists of for it to appear in
diff --git a/misc/abi-compliance-checker.txt b/misc/abi-compliance-checker.txt
new file mode 100644
index 000000000..097daeedb
--- /dev/null
+++ b/misc/abi-compliance-checker.txt
@@ -0,0 +1,143 @@
+============================================================================
+ How to use `abi-compliance-checker' to test FLTK ABI compatibility (Linux)
+============================================================================
+
+This howto uses directories in /git/ as example directories. Please
+adjust versions and directory names as appropriate on your system.
+
+In this howto we compare FLTK 1.3.4-1 (last 1.3.x release as of Jan 02, 2019)
+with the current version (1.3.5) before it will be released.
+
+
+(1) Download 'abi-compliance-checker' from GitHub:
+
+    $ cd /git
+    $ git clone https://github.com/lvc/abi-compliance-checker.git
+
+    Download directory: /git/abi-compliance-checker/
+
+
+(2) Use two different Git checkout (working) directories to build libs,
+    for instance (as used in this example):
+
+    (new) /git/fltk-1.3		current  version = 1.3.5
+    (old) /git/fltk-1.3.4-1	previous version = 1.3.4-1	[1]
+
+    [1] The second working directory can be created from the first
+	git working tree ( /git/fltk-1.3 ) with these commands:
+
+	$ cd /git/fltk-1.3
+	$ git worktree add /git/fltk-1.3.4-1 release-1.3.4-1
+
+	This creates the worktree in /git/fltk-1.3.4-1 and checks the
+	tag 'release-1.3.4-1' out.
+
+
+(3) Create two xml descriptions to test library compatibility in
+    an arbitrary working directory (here: /git/workdir):
+
+--- fltk-1.3.4-1.xml ---
+<version>
+    1.3.4-1
+</version>
+
+<headers>
+    /git/fltk-1.3.4-1/FL/
+</headers>
+
+<skip_headers>
+    win32.H
+    mac.H
+</skip_headers>
+
+<libs>
+    /git/fltk-1.3.4-1/src/
+    /git/fltk-1.3.4-1/cairo/
+</libs>
+--- end of file ---
+
+--- fltk-1.3.5.xml ---
+<version>
+    1.3.5
+</version>
+
+<headers>
+    /git/fltk-1.3/FL/
+</headers>
+
+<skip_headers>
+    win32.H
+    mac.H
+</skip_headers>
+
+<libs>
+    /git/fltk-1.3/src/
+    /git/fltk-1.3/cairo/
+</libs>
+--- end of file ---
+
+
+(4) Configure and build both libraries with the same options.
+    You *must* include '--enable-cairo' to build and compare the
+    Cairo libs and '--enable-shared' to build the shared libs:
+
+    $ make clean
+    $ ./configure --enable-cairo --enable-shared --enable-debug
+    $ make
+
+    Note: you must *not* use '--with-abiversion' because we need to
+    build the default ABI version.
+
+
+(5) Run `abi-compliance-checker.pl':
+
+    $ cd /git/workdir
+    $ /git/abi-compliance-checker/abi-compliance-checker.pl \
+        -lib fltk -old fltk-1.3.4-1.xml -new fltk-1.3.5.xml
+	Preparing, please wait ...
+	Using GCC 7 (x86_64-linux-gnu, target: x86_64)
+	WARNING: May not work properly with GCC 4.8.[0-2], 6.* and higher
+	due to bug #78040 in GCC. Please try other GCC versions with the
+	help of --gcc-path=PATH option or create ABI dumps by ABI Dumper
+	tool instead to avoid using GCC. Test selected GCC version first
+	by -test option.
+	------------------------------------------------------------------
+	--> ignore warning (but run `abi-compliance-checker.pl -test')
+	------------------------------------------------------------------
+	Checking header(s) 1.3.4-1 ...
+	WARNING: can't find 'ctags' program
+	Checking header(s) 1.3.5 ...
+	WARNING: can't find 'ctags' program
+	------------------------------------------------------------------
+	--> ignore warning (or install 'ctags' and repeat)
+	------------------------------------------------------------------
+	Comparing ABIs ...
+	Comparing APIs ...
+	Creating compatibility report ...
+	Binary compatibility: 100%
+	Source compatibility: 100%
+	Total binary compatibility problems: 0, warnings: 0
+	Total source compatibility problems: 0, warnings: 1
+	Report: compat_reports/fltk/1.3.4-1_to_1.3.5/compat_report.html
+
+
+(6) Check the generated report (last line above) with a browser:
+
+    $ firefox compat_reports/fltk/1.3.4-1_to_1.3.5/compat_report.html
+
+
+(7) You may want to remove the additional worktree created above with:
+
+    $ cd /git/fltk-1.3
+    $ git worktree remove --force /git/fltk-1.3.4-1
+
+
+(8) Done.
+
+
+Note 1:	The report as given above issued 100% ABI compatibility. The only
+	warning was the different patch version number.
+
+Note 2:	There are other recommended methods to use abi-compliance-checker
+	together with abi-dumper, but this is not (yet) covered here (see
+	abi-compliance-checker documentation).
diff --git a/src/Fl_cocoa.mm b/src/Fl_cocoa.mm
index 2d6f6d453..d5fc1c9a9 100644
--- a/src/Fl_cocoa.mm
+++ b/src/Fl_cocoa.mm
@@ -594,10 +594,12 @@ void Fl_Cocoa_Screen_Driver::breakMacEventLoop()
   CGContextRef layer_data;
 }
 - (void)displayLayer:(CALayer *)layer;
+- (void)prepare_bitmap_for_layer;
 - (void)viewFrameDidChange;
 - (BOOL)wantsLayer;
 - (void)dealloc;
 - (BOOL)did_view_resolution_change;
+- (void)drawRect:(NSRect)rect;
 @end
 #endif //10_8
 
@@ -2176,12 +2178,6 @@ static FLTextInputContext* fltextinputcontext_instance = nil;
  */
 
 #if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_8
-static CGContextRef prepare_bitmap_for_layer(int w, int h ) {
-  static CGColorSpaceRef cspace = CGColorSpaceCreateDeviceRGB();
-  CGContextRef gc = CGBitmapContextCreate(NULL,  w,  h, 8, 4 * w, cspace, kCGImageAlphaPremultipliedFirst);
-  CGContextClearRect(gc, CGRectMake(0,0,w,h));
-  return gc;
-}
 
 @interface FLGLViewLayer : FLView // for layer-backed GL windows
 #if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_12
@@ -2238,11 +2234,10 @@ static CGContextRef prepare_bitmap_for_layer(int w, int h ) {
 - (BOOL)wantsLayer {
   return YES;
 }
-
 - (void)displayLayer:(CALayer *)layer {
-  // called if views are layered (but not for GL) : all drawing to window goes through this
+  // used by non-GL layer-backed views
   Fl_Window *window = [(FLWindow*)[self window] getFl_Window];
-  Fl_Cocoa_Window_Driver *d = Fl_Cocoa_Window_Driver::driver(window);
+  if (!window) return; // needed e.g. when closing a tab in a window
   float scale = Fl::screen_driver()->scale(0);
   NSRect rect = [self frame];
   if (!window->parent() && window->border() && fabs(rect.size.height - window->h() * scale) > 5. ) {
@@ -2253,44 +2248,57 @@ static CGContextRef prepare_bitmap_for_layer(int w, int h ) {
     [self viewFrameDidChange];
   }
   if (!layer_data) { // runs when window is created, resized, changed screen resolution
-    layer.bounds = NSRectToCGRect(rect);
-    [self did_view_resolution_change];
-    d->wait_for_expose_value = 0;
-    if (d->mapped_to_retina()) {
-      rect.size.width *= 2; rect.size.height *= 2;
-      layer.contentsScale = 2.;
-    } else layer.contentsScale = 1.;
-    layer_data = prepare_bitmap_for_layer(rect.size.width, rect.size.height);
+    [self prepare_bitmap_for_layer];
     Fl_X *i = Fl_X::i(window);
     if ( i->region ) {
       Fl_Graphics_Driver::default_driver().XDestroyRegion(i->region);
       i->region = 0;
     }
     window->clear_damage(FL_DAMAGE_ALL);
-  }
-  if (window->damage()) {
-    through_drawRect = YES;
-    d->Fl_Window_Driver::flush();
+    through_Fl_X_flush = YES;
+    Fl_Cocoa_Window_Driver::driver(window)->Fl_Window_Driver::flush();
     Fl_Cocoa_Window_Driver::q_release_context();
-    through_drawRect = NO;
+    through_Fl_X_flush = NO;
     window->clear_damage();
-    if (layer_data) {
-      CGImageRef cgimg = CGBitmapContextCreateImage(layer_data);  // requires 10.4
-      layer.contents = (id)cgimg;
-      CGImageRelease(cgimg);
-    }
+  }
+  if (layer_data) {
+    CGImageRef cgimg = CGBitmapContextCreateImage(layer_data);  // requires 10.4
+    layer.contents = (id)cgimg;
+    CGImageRelease(cgimg);
   }
 }
+- (void)prepare_bitmap_for_layer {
+  Fl_Window *window = [(FLWindow*)[self window] getFl_Window];
+  Fl_Cocoa_Window_Driver *d = Fl_Cocoa_Window_Driver::driver(window);
+  CALayer *layer = [self layer];
+  NSRect rect = [self frame];
+  layer.bounds = NSRectToCGRect(rect);
+  [self did_view_resolution_change];
+  d->wait_for_expose_value = 0;
+  if (d->mapped_to_retina()) {
+    rect.size.width *= 2; rect.size.height *= 2;
+    layer.contentsScale = 2.;
+  } else layer.contentsScale = 1.;
+  static CGColorSpaceRef cspace = CGColorSpaceCreateDeviceRGB();
+  layer_data = CGBitmapContextCreate(NULL,  rect.size.width,  rect.size.height, 8, 4 * rect.size.width, cspace, kCGImageAlphaPremultipliedFirst);
+  CGContextClearRect(layer_data, CGRectMake(0,0,rect.size.width,rect.size.height));
+}
 - (BOOL)did_view_resolution_change {
   BOOL retval = [super did_view_resolution_change];
   if (retval) {
     [self viewFrameDidChange];
-    [self displayLayer:[self layer]]; // useful for Mandelbrot to recreate the layer's bitmap
+    [(FLWindow*)[self window] getFl_Window]->redraw();
+    [self setNeedsDisplay:YES];
   }
   return retval;
 }
 -(void)viewFrameDidChange
 {
+  Fl_Window *win = [(FLWindow*)[self window] getFl_Window];
+  if (win) { // can be null when window is set fullscreen
+    Fl_Cocoa_Window_Driver::q_release_context(Fl_Cocoa_Window_Driver::driver(win));
+    win->redraw();
+  }
   CGContextRelease(layer_data);
   layer_data = NULL;
 }
@@ -2298,6 +2306,7 @@ static CGContextRef prepare_bitmap_for_layer(int w, int h ) {
   CGContextRelease(layer_data);
   [super dealloc];
 }
+- (void)drawRect:(NSRect)rect {} // necessary under 10.14.2 to support gl_start()
 @end
 #endif //>= MAC_OS_X_VERSION_10_8
 
@@ -2965,7 +2974,12 @@ void Fl_Cocoa_Window_Driver::flush()
 #if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_8
   } else if (views_use_CA) {
     FLViewLayer *view = (FLViewLayer*)[fl_xid(pWindow) contentView];
-    [view displayLayer:[view layer]];
+    if (!view->layer_data) [view prepare_bitmap_for_layer];
+    through_Fl_X_flush = YES;
+    Fl_Window_Driver::flush();
+    through_Fl_X_flush = NO;
+    q_release_context();
+    [view setNeedsDisplay:YES];
 #endif
   } else {
     make_current_counts = 1;
@@ -3414,8 +3428,10 @@ void Fl_Cocoa_Window_Driver::make_current()
 {
   if (make_current_counts > 1 && !views_use_CA) return;
   if (make_current_counts) make_current_counts++;
-  if (views_use_CA && !through_drawRect) { // detect direct calls from the app
-    pWindow->damage(FL_DAMAGE_CHILD); // make next draws to this window displayed at next event loop
+  if (views_use_CA && !through_Fl_X_flush) { // detect direct calls from the app
+    FLViewLayer *view = (FLViewLayer*)[fl_window contentView];
+    if (!view->layer_data) [view prepare_bitmap_for_layer]; // necessary for progressive drawing
+    [view setNeedsDisplay:YES];
   }
   q_release_context();
   Fl_X *i = Fl_X::i(pWindow);
@@ -3431,12 +3447,8 @@ void Fl_Cocoa_Window_Driver::make_current()
   if (views_use_CA) {
     gc = ((FLViewLayer*)[fl_window contentView])->layer_data;
 #  ifdef FLTK_HAVE_CAIRO
-    // make sure the GC starts with an identity transformation matrix as do native Cocoa GC's
-    // because cairo may have changed it 
-    CGAffineTransform mat = CGContextGetCTM(gc);
-    if (!CGAffineTransformIsIdentity(mat)) { // 10.4
-      CGContextConcatCTM(gc, CGAffineTransformInvert(mat));
-    }
+    // necessary because cairo may have changed the Quartz context
+    CGContextSaveGState(gc);
 #  endif
   } else
 #endif
@@ -3482,6 +3494,9 @@ void Fl_Cocoa_Window_Driver::q_release_context(Fl_Cocoa_Window_Driver *x) {
   if (!gc) return;
   CGContextRestoreGState(gc); // match the CGContextSaveGState's of make_current
   CGContextRestoreGState(gc);
+#if defined(FLTK_HAVE_CAIRO)
+  if (views_use_CA) CGContextRestoreGState(gc);
+#endif
   CGContextFlush(gc);
   Fl_Graphics_Driver::default_driver().gc(0);
 #if defined(FLTK_USE_CAIRO)