diff options
| -rw-r--r-- | CMakeLists.txt | 6 | ||||
| -rw-r--r-- | documentation/CMakeLists.txt | 4 | ||||
| -rw-r--r-- | documentation/Doxyfile.in | 8 | ||||
| -rw-r--r-- | documentation/src/unicode.dox | 10 | ||||
| -rw-r--r-- | fluid/widgets/Code_Editor.h | 1 | ||||
| -rw-r--r-- | util/CMakeLists.txt | 76 | ||||
| -rw-r--r-- | util/README.txt | 13 | ||||
| -rw-r--r-- | util/code_snapshot.cxx | 159 |
8 files changed, 274 insertions, 3 deletions
diff --git a/CMakeLists.txt b/CMakeLists.txt index b846da477..6da0edc94 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -258,6 +258,12 @@ if(FLTK_BUILD_FLTK_OPTIONS) endif(FLTK_BUILD_FLTK_OPTIONS) ####################################################################### +# build utilities +####################################################################### + +add_subdirectory(util) + +####################################################################### # variables shared by export and install # export.cmake creates configuration files for direct use in a built but uninstalled FLTK # install.cmake creates these files for an installed FLTK diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt index 3dc9fbd1b..bbf8da6ae 100644 --- a/documentation/CMakeLists.txt +++ b/documentation/CMakeLists.txt @@ -103,6 +103,7 @@ if(FLTK_BUILD_HTML_DOCS) set(GENERATE_HTML YES) set(GENERATE_LATEX NO) + set(EXTRA_SECTIONS "HTML_SECTIONS") set(LATEX_HEADER "") set(DOXYFILE "Doxyfile") set(LOGFILE "${CMAKE_CURRENT_BINARY_DIR}/${DOXYFILE}_error.log") @@ -152,6 +153,7 @@ if(FLTK_BUILD_PDF_DOCS) set(GENERATE_HTML NO) set(GENERATE_LATEX YES) + set(EXTRA_SECTIONS "LATEX_SECTIONS") set(LATEX_HEADER "${CMAKE_CURRENT_BINARY_DIR}/fltk-book.tex") set(DOXYFILE "Doxybook") set(LOGFILE "${CMAKE_CURRENT_BINARY_DIR}/${DOXYFILE}_error.log") @@ -202,6 +204,7 @@ if(FLTK_BUILD_PDF_DOCS) add_custom_command( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/fltk.pdf + COMMAND code_snapshot ${CMAKE_CURRENT_SOURCE_DIR}/src/unicode.dox COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/make_header ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/fltk-title.tex @@ -220,6 +223,7 @@ if(FLTK_BUILD_PDF_DOCS) add_custom_target(pdf DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/fltk.pdf ) + add_dependencies(pdf code_snapshot) endif(FLTK_BUILD_PDF_DOCS) diff --git a/documentation/Doxyfile.in b/documentation/Doxyfile.in index d1dec82db..10c277a72 100644 --- a/documentation/Doxyfile.in +++ b/documentation/Doxyfile.in @@ -229,7 +229,8 @@ TAB_SIZE = 8 # newlines (in the resulting output). You can put ^^ in the value part of an # alias to insert a newline as if a physical newline was in the original file. -ALIASES = +ALIASES = code_international{1}="@if LATEX_SECTIONS^^@image latex \1 width=\\linewidth^^@endif^^@if HTML_SECTIONS^^@code" +ALIASES += endcode_international="@endcode^^@endif" # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding "class=itcl::class" @@ -639,7 +640,7 @@ GENERATE_DEPRECATEDLIST= YES # sections, marked by \if <section_label> ... \endif and \cond <section_label> # ... \endcond blocks. -ENABLED_SECTIONS = @DRIVER_DOCS@ +ENABLED_SECTIONS = @DRIVER_DOCS@ @EXTRA_SECTIONS@ # The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the # initial value of a variable or macro / define can have for it to appear in the @@ -920,7 +921,8 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = @CMAKE_CURRENT_SOURCE_DIR@/src +IMAGE_PATH = @CMAKE_CURRENT_SOURCE_DIR@/src \ + @CMAKE_CURRENT_BINARY_DIR@/generated # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program diff --git a/documentation/src/unicode.dox b/documentation/src/unicode.dox index b2eb7b872..b640e170e 100644 --- a/documentation/src/unicode.dox +++ b/documentation/src/unicode.dox @@ -20,6 +20,16 @@ are not yet implemented. \section unicode_quick_start Quick Start +International code test for HTML and PDF: + +\code_international{"generated/unicode_about.png"} +// This is a test +// 日本語テストテキスト +// 中文测试文本 +// Ελληνικό κείμενο δοκιμής +\endcode_international + + For most applications, you simply need to ensure your text is UTF-8 encoded: \code diff --git a/fluid/widgets/Code_Editor.h b/fluid/widgets/Code_Editor.h index 49afe7e25..fec57727c 100644 --- a/fluid/widgets/Code_Editor.h +++ b/fluid/widgets/Code_Editor.h @@ -53,6 +53,7 @@ public: Code_Editor(int X, int Y, int W, int H, const char *L=nullptr); ~Code_Editor(); void textsize(Fl_Fontsize s); + Fl_Fontsize textsize() const { return Fl_Text_Editor::textsize(); } /// access to protected member get_absolute_top_line_number() int top_line() { return get_absolute_top_line_number(); } diff --git a/util/CMakeLists.txt b/util/CMakeLists.txt new file mode 100644 index 000000000..a89413a19 --- /dev/null +++ b/util/CMakeLists.txt @@ -0,0 +1,76 @@ +# +# CMakeLists.txt to build utilities for the FLTK project using CMake (www.cmake.org) +# +# Copyright 1998-2025 by Bill Spitzak and others. +# +# This library is free software. Distribution and use rights are outlined in +# the file "COPYING" which should have been included with this file. If this +# file is missing or damaged, see the license at: +# +# https://www.fltk.org/COPYING.php +# +# Please see the following page on how to report bugs and issues: +# +# https://www.fltk.org/bugs.php +# + +# Build utilities for FLTK development + +# Note: utilities are only built internally during the build process +# and not installed. They are tools used to generate source files or +# assist in building documentation. + +####################################################################### +# cmap - colormap generation program +####################################################################### + +# This program produces the contents of "fl_cmap.h" +# It's used during the build process to generate src/fl_cmap.h + +add_executable(cmap cmap.cxx) + +# cmap doesn't need to link against FLTK libraries - it's a standalone tool +target_link_libraries(cmap PRIVATE m) + +# Set properties +set_target_properties(cmap PROPERTIES + OUTPUT_NAME cmap + EXCLUDE_FROM_ALL TRUE +) + +####################################################################### +# PDF documentation tool to generate a png image from a +# Doxygen `@code` segment with international characters +####################################################################### + +if(FLTK_BUILD_PDF_DOCS) + + # PDF documentation helper tool + add_executable(code_snapshot + code_snapshot.cxx + ../fluid/Widgets/Code_Viewer.cxx + ../fluid/Widgets/Code_Editor.cxx + ../fluid/Widgets/Style_Parser.cxx + ) + + target_link_libraries(code_snapshot PRIVATE fltk::images) + + set_target_properties(code_snapshot PROPERTIES + OUTPUT_NAME code_snapshot + EXCLUDE_FROM_ALL FALSE + ) + + target_include_directories(code_snapshot PRIVATE + ../fluid + ) + + message(STATUS "PDF code snapshot tools will be built (FLTK_BUILD_PDF_DOCS=ON)") + +endif(FLTK_BUILD_PDF_DOCS) + +####################################################################### +# Install rules (if any tools need to be installed) +####################################################################### + +# Currently no utilities are installed as they are build-time tools only +# If you need to install any utilities, add install() commands here diff --git a/util/README.txt b/util/README.txt index bfafb80fd..c71f6b147 100644 --- a/util/README.txt +++ b/util/README.txt @@ -4,3 +4,16 @@ Utility programs used to build the FLTK library. Contents: cmap.cxx generate src/fl_cmap.h + code_snapshot.cxx PDF documentation tool to generate a png image from a + Doxygen `@code` segment with international characters + +Build System: + + The util directory includes CMake support. Utilities are built + automatically during the build process when needed. Some utilities + are only built when specific features are enabled: + + - the PDF documentation helper is only built when FLTK_BUILD_PDF_DOCS=ON + + To add a new utility, edit util/CMakeLists.txt and follow the existing + patterns for conditional building and target configuration. diff --git a/util/code_snapshot.cxx b/util/code_snapshot.cxx new file mode 100644 index 000000000..a8a2f2cae --- /dev/null +++ b/util/code_snapshot.cxx @@ -0,0 +1,159 @@ +// +// PDF documentation tool to generate a png image from a Doxygen `@code` +// segment with international characters for the Fast Light Tool Kit (FLTK). +// +// Copyright 2025 by Bill Spitzak and others. +// +// This library is free software. Distribution and use rights are outlined in +// the file "COPYING" which should have been included with this file. If this +// file is missing or damaged, see the license at: +// +// https://www.fltk.org/COPYING.php +// +// Please see the following page on how to report bugs and issues: +// +// https://www.fltk.org/bugs.php +// + +// +// Our documentation for the FLTK unicode contains international characters +// to illustrate use of non ASCII characters in the GUI. To generate PDF +// output, Doxygen uses LaTeX which can not easily handle UTF-8 characters in +// beyond Western encoding. This tool generates PNG images from code segments +// containing international characters so that they can be included in the +// PDF documentation instead of the code segments with UTF-8 characters. +// + +#include <stdio.h> + +#include <FL/Fl_Window.H> +#include <FL/Fl_Group.H> +#include <FL/filename.H> +#include <FL/fl_draw.H> +#include <FL/Fl_Image_Surface.H> +#include <FL/Fl_PNG_Image.H> + +#include "../fluid/widgets/Code_Editor.h" +#include "../fluid/widgets/Code_Viewer.h" +#include "../fluid/widgets/Style_Parser.h" + +Fl_Window* window = nullptr; +Fl_Group* group = nullptr; +fld::widget::Code_Viewer* code_viewer = nullptr; + +void create_window() { + window = new Fl_Window(1024, 100); + group = new Fl_Group(0, 0, 1024, 100); + group->color(0xf7f7ff00); + group->box(FL_FLAT_BOX); + + code_viewer = new fld::widget::Code_Viewer(5, 5, 1014, 94); + code_viewer->box(FL_FLAT_BOX); + code_viewer->color(0xf7f7ff00); + code_viewer->textsize(30); + + window->resizable(group); + group->resizable(code_viewer); +} + +void save_snapshot(const char* code, const char* filename) +{ +// fprintf(stderr, "\\code\n%s\n\\endcode\n", code); + + code_viewer->buffer()->text(code); + int n_lines = 1; + for (const char* s=code; *s; ++s) if (*s == '\n') n_lines++; + // 300 dpi for 7 inches = 2000 pixels + window->size(2100, 6 + 34*n_lines ); + + // Generate the Image Surface + Fl_Image_Surface *srfc = new Fl_Image_Surface(window->w(), window->h()); + + // Draw the window and its content + Fl_Image_Surface::push_current(srfc); + srfc->draw(group, 0, 0); + fl_rect(0, 0, window->w(), window->h(), 0xccccff00); + Fl_Image_Surface::pop_current(); + +// fprintf(stderr, " Saving to \"%s\".\n", filename); + + // Write the generated image + Fl_RGB_Image *img = srfc->image(); + fl_write_png(filename, img); + + // Clean up + delete img; + delete srfc; +} + +/** + Main entry point for the PDF documentation helper tool. + + The app scans the input file for the `\\code_international{"filename"}` + directive, reads the following code segment until + `\\endcode_international`, and generates a PNG image file with the given + filename containing the code segment rendered with FLTK's + code rendering capabilities. + + \param argc Argument count + \param argv a list of input files with documentation in Doxygen format + \return Exit code (0 for success, non-zero for failure) +*/ +int main(int argc, char *argv[]) +{ + int ret = 0; + char line[1024]; + char cwd[FL_PATH_MAX]; + +// fl_getcwd(cwd, FL_PATH_MAX-1); +// fprintf(stderr, "code_snapshot:\n"); +// fprintf(stderr, "Working directory is \"%s\".\n", cwd); + + create_window(); + + for (int i = 1; i < argc; i++) { + FILE* f = fl_fopen(argv[i], "rb"); + if (!f) { + fl_getcwd(cwd, FL_PATH_MAX-1); + fprintf(stderr, "code_snapshot:\nCan't open file \"%s\".\n", argv[i]); + fprintf(stderr, "Working directory is \"%s\".\n", cwd); + ret = -1; + break; + } + +// fprintf(stderr, "Reading \"%s\".\n", argv[i]); + + std::string code; + std::string filename; + bool in_code_block = false; + for (;;) { + fgets(line, 1023, f); + if (feof(f)) break; + if (in_code_block) { + if (strstr(line, "\\endcode_international")) { + if (!code.empty()) { + code.resize( code.size()-1 ); + save_snapshot(code.c_str(), filename.c_str()); + } + in_code_block = false; + } else { + code += line; + } + } else { + if (strstr(line, "\\code_international")) { + const char* fn_start = strstr(line, "{\""); + const char* fn_end = strstr(line, "\"}"); + if (fn_start && fn_end && (fn_end > fn_start)) { + filename = std::string(fn_start+2, fn_end-fn_start-2); + in_code_block = true; + } + } + } + } + fclose(f); + } + + delete window; + + return ret; +} |