From de199c327e9b55bd615f7262724da8ecba1999cf Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Sat, 29 Dec 2018 20:04:38 +0100 Subject: Add a CMake option to generate driver (developer) documentation. Generating driver documentation can now be configured with CMake. The new configuration OPTION_INCLUDE_DRIVER_DOCUMENTATION is "marked as advanced" since only advanced users and/or FLTK developers need this. Previously this could only be achieved by editing documentation/Doxyfile.in. Added missing documentation option descriptions as well. --- CMake/options.cmake | 4 ++++ README.CMake.txt | 31 +++++++++++++++++++++++++++---- documentation/CMakeLists.txt | 10 ++++++++-- documentation/Doxyfile.in | 3 +-- 4 files changed, 40 insertions(+), 8 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/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 -- cgit v1.2.3 From 26bb0e5a831be64f21eec41efef73571aebadab5 Mon Sep 17 00:00:00 2001 From: Manolo Gouy Date: Sun, 30 Dec 2018 10:59:53 +0100 Subject: Under macOS 10.14, Fl_Cocoa_Window_Driver::flush() draws to the bitmap and does [view setNeedsDisplay:YES] --- src/Fl_cocoa.mm | 89 +++++++++++++++++++++++++++++++++------------------------ 1 file changed, 52 insertions(+), 37 deletions(-) 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) -- cgit v1.2.3 From ca8c5feb1640f1d9da2cfb30346fb63fbfaa7fea Mon Sep 17 00:00:00 2001 From: Manolo Gouy Date: Mon, 31 Dec 2018 16:03:46 +0100 Subject: Document global variable fl_sys_menu_bar. --- FL/Fl_Sys_Menu_Bar.H | 1 + FL/mac.H | 4 ---- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/FL/Fl_Sys_Menu_Bar.H b/FL/Fl_Sys_Menu_Bar.H index 551ebc387..2f282df1e 100644 --- a/FL/Fl_Sys_Menu_Bar.H +++ b/FL/Fl_Sys_Menu_Bar.H @@ -102,6 +102,7 @@ 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 { -- cgit v1.2.3 From e118532c724e271644463b40b50eafcf11d27f17 Mon Sep 17 00:00:00 2001 From: Manolo Gouy Date: Mon, 31 Dec 2018 16:37:36 +0100 Subject: Document global variable fl_sys_menu_bar - continued. --- FL/Fl_Sys_Menu_Bar.H | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/FL/Fl_Sys_Menu_Bar.H b/FL/Fl_Sys_Menu_Bar.H index 2f282df1e..4d009a26c 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 @@ -102,7 +107,8 @@ public: static void create_window_menu(); }; -/** The system menu bar. */ +/** The system menu bar. + */ extern Fl_Sys_Menu_Bar *fl_sys_menu_bar; #endif // Fl_Sys_Menu_Bar_H -- cgit v1.2.3 From f28cead0f0a21af54b30abe198ad09b7e240dff0 Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Wed, 2 Jan 2019 15:33:34 +0100 Subject: Add abi-compliance-checker howto. This is intentionally committed to the 'master' branch although it is currently only useful for FLTK 1.3.x ABI checks. In the future we will need it for FLTK 1.4.x or higher. --- misc/abi-compliance-checker.txt | 143 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 misc/abi-compliance-checker.txt 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 --- + + 1.3.4-1 + + + + /git/fltk-1.3.4-1/FL/ + + + + win32.H + mac.H + + + + /git/fltk-1.3.4-1/src/ + /git/fltk-1.3.4-1/cairo/ + +--- end of file --- + +--- fltk-1.3.5.xml --- + + 1.3.5 + + + + /git/fltk-1.3/FL/ + + + + win32.H + mac.H + + + + /git/fltk-1.3/src/ + /git/fltk-1.3/cairo/ + +--- 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). -- cgit v1.2.3 From b027da8322cde4bc33cf7e85a113365abe2b69c3 Mon Sep 17 00:00:00 2001 From: Manolo Gouy Date: Wed, 2 Jan 2019 19:41:44 +0100 Subject: Document global variable fl_sys_menu_bar - continued. --- FL/Fl_Sys_Menu_Bar.H | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/FL/Fl_Sys_Menu_Bar.H b/FL/Fl_Sys_Menu_Bar.H index 4d009a26c..ecf72ff15 100644 --- a/FL/Fl_Sys_Menu_Bar.H +++ b/FL/Fl_Sys_Menu_Bar.H @@ -49,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 -- cgit v1.2.3