wxruby3-mdap 1.0.0.pre.rc.1

data/lib/wx/mdap/provider.rb

@@ -0,0 +1,248 @@
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+
+
+module Wx
+
+  module MDAP
+
+    # Material Design art provider class.
+    #
+    # This derived {https://mcorino.github.io/wxRuby3/Wx/ArtProvider.html Wx::ArtProvider} class implements all
+    # required overrides to support the full functionality of `Wx::ArtProvider` to access a set of Material Design
+    # SVG Art consisting of nearly 9000 images distributed over 11 lists from Fluent UI, Font Awesome, Material Design
+    # and Simple Icons collections (see the {file:README.md} for more information).<br>
+    #
+    # ## Identifying art resources
+    #
+    # Each list from these collections has been mapped to a distinct Art Client id and for each image a distinct
+    # Art id has been defined.<br>
+    # See {Wx::MDAP here} for all defined Art (Client) id constants.<br>
+    #
+    # ## Art overviews
+    #
+    # Overviews of the available icons for the various Art Client id/Art id combinations can be found at the
+    # following locations:
+    #
+    # - {file:FLUENT_UI-Art.md Fluent UI art}
+    # - {file:FONT_AWESOME-Art.md Font Awesome art}
+    # - {file:MATERIAL_DESIGN-Art.md Material Design art}
+    # - {file:SIMPLE_ICONS-Art.md Simple Icons art}
+    #
+    # ## Extensions
+    #
+    # The MaterialDesignArtProvider class provides a number of extensions to customize the default colour and default
+    # size for MaterialDesignArtProvider returned images as well a mapping scheme for standard wxRuby3 Art (Client) ids
+    # to MaterialDesignArtProvider specific ids.
+    #
+    # ### Managing Art colour
+    #
+    # By default MaterialDesignArtProvider will return images in the colour as defined in the original SVG which is
+    # usually BLACK.
+    # This can be overridden by using either of 2 methods; {.use_art_colour} and/or {.with_art_colour}.
+    #
+    # ### Managing Art size
+    #
+    # When requesting images from MaterialDesignArtProvider with `Wx::DEFAULT_SIZE` by default the size used will be
+    # derived from {https://mcorino.github.io/wxRuby3/Wx/ArtProvider.html#get_native_size_hint-class_method Wx::ArtProvider.get_native_size_hint}.
+    # In case this returns `Wx::DEFAULT_SIZE` itself the default will be `Wx::Size.new(24,24)`.
+    # This can be overridden by using {.set_default_size}. Use {.get_default_size} to see what the current default size
+    # will be.
+    #
+    # ### Mapping standard wxRuby3 Art ids
+    #
+    # MaterialDesignArtProvider implements a **fixed** mapping scheme for mapping standard wxRuby3 Art ids (like
+    # `Wx::ART_ERROR`, `Wx::FILE_SAVE`, `Wx::ART_FOLDER` etc.) to MaterialDesignArtProvider Art ids (defined in {Wx::MDAP}).
+    # An overview of this mapping scheme can be found {file:STANDARD-Art-Mappings.md  here}.<br>
+    # In addition to that MaterialDesignArtProvider implements a customizable mapping scheme for mapping standard
+    # wxRuby3 Art Client ids (like `Wx::ART_MENU`, `Wx::ART_TOOLBAR`, `Wx::ART_OTHER` etc.) to MaterialDesignArtProvider
+    # Art Client ids (defined in {Wx::MDAP}).
+    # By default all standard Art Client ids are mapped to {Wx::MDAP::ART_FLUENT_UI_REGULAR}. This can be overridden by
+    # using {.map_std_client_id}.
+    #
+    class MaterialDesignArtProvider < Wx::ArtProvider
+
+      class << self
+
+        private
+
+        # Returns the current default Material Design Art colour
+        # (default `nil` meaning to use the SVG images 'as-is')
+        def art_colour
+          @art_colour
+        end
+
+        # (Re)Sets the default Material Design Art colour
+        def set_art_colour(colour)
+          @art_colour = if colour.is_a?(Wx::Colour)
+                          colour
+                        else
+                          colour ? Wx::Colour.new(colour) : nil
+                        end
+        end
+
+        # Returns the registry of the default sizes for each Material Design Art client
+        def default_sizes
+          @def_sizes ||= {}
+        end
+
+        # Returns a list of the standard wxRuby3 Art Client ids
+        def std_client_ids
+          @std_client_ids ||= [
+            Wx::ART_TOOLBAR,
+            Wx::ART_MENU,
+            Wx::ART_BUTTON,
+            Wx::ART_FRAME_ICON,
+            Wx::ART_CMN_DIALOG,
+            Wx::ART_HELP_BROWSER,
+            Wx::ART_MESSAGE_BOX,
+            Wx::ART_OTHER]
+        end
+
+        # Returns the registry mapping standard wxRuby3 Art Client ids to Material Design Art Client ids.
+        # If no mapping specified the default mapping will be {Wx::MDAP::ART_FLUENT_UI_REGULAR}
+        def std_client_id_map
+          @std_client_id_map ||= ::Hash.new(Wx::MDAP::ART_FLUENT_UI_REGULAR)
+        end
+
+        public
+
+        # Sets the active colour to use for created MaterialDesign art.
+        # By default the colour is `nil` (which is equivalent to :BLACK).
+        # @param [Wx::Colour,String,Symbol,nil] colour
+        def use_art_colour(colour)
+          set_art_colour(colour)
+        end
+
+        # Sets the active colour to use for created MaterialDesign art in the scope of the given block.
+        # After the block returns the colour is restored to it's setting from before the block.
+        # @param [Wx::Colour,String,Symbol,nil] colour
+        def with_art_colour(colour)
+          prev_colour = art_colour
+          begin
+            set_art_colour(colour)
+            yield if block_given?
+          ensure
+            set_art_colour(prev_colour)
+          end
+        end
+
+        # Returns the default art size for the given (standard or Material Design) Art Client id.
+        # By default will derive default from {Wx::ArtProvider.get_native_size_hint}.
+        # @param [String] client Art Client id
+        # @return [Wx::size]
+        def get_default_size(client)
+          raise ArgumentError, "Invalid art client id [#{client}]" unless std_client_ids.include?(client) || MDAP.has_art_client_id?(client)
+          unless default_sizes.has_key?(client)
+            def_sz = Wx::ArtProvider.get_native_size_hint(client)
+            default_sizes[client] = (def_sz == Wx::DEFAULT_SIZE ? Wx::Size.new(24,24) : def_sz)
+          end
+          default_sizes[client]
+        end
+
+        # Sets the default art size for the given (standard or Material Design) Art Client id.
+        # @param [String] client Art Client id
+        # @param [Wx::Size,Array(Integer,Integer)] size
+        def set_default_size(client, size)
+          raise ArgumentError, "Invalid art client id [#{client}]" unless std_client_ids.include?(client) || MDAP.has_art_client_id?(client)
+          default_sizes[client] = size.to_size
+        end
+
+        # Sets the MDAP client id to use when a std wxRuby3 ClientArtId is passed to {MaterialDesignArtProvider}.
+        # By default the alternative id used for any standard id is {Wx::MDAP::ART_FLUENT_UI_REGULAR}.
+        # The `std_client_id` passed should be one of:
+        #
+        # - {Wx::ART_TOOLBAR}
+        # - {Wx::ART_MENU}
+        # - {Wx::ART_BUTTON}
+        # - {Wx::ART_FRAME_ICON}
+        # - {Wx::ART_CMN_DIALOG}
+        # - {Wx::ART_HELP_BROWSER}
+        # - {Wx::ART_MESSAGE_BOX}
+        # - {Wx::ART_OTHER}
+        #
+        # The `md_client_id` passed should be one of:
+        #
+        # - {Wx::MDAP::ART_FLUENT_UI_REGULAR}
+        # - {Wx::MDAP::ART_FLUENT_UI_FILLED}
+        # - {Wx::MDAP::ART_FONT_AWESOME_REGULAR}
+        # - {Wx::MDAP::ART_FONT_AWESOME_SOLID}
+        # - {Wx::MDAP::ART_MATERIAL_DESIGN_FILLED}
+        # - {Wx::MDAP::ART_MATERIAL_DESIGN_OUTLINED}
+        # - {Wx::MDAP::ART_MATERIAL_DESIGN_ROUND}
+        # - {Wx::MDAP::ART_MATERIAL_DESIGN_SHARP}
+        # - {Wx::MDAP::ART_MATERIAL_DESIGN_TWO_TONE}
+        #
+        # @param [String] std_client_id the standard client id to map
+        # @param [String] md_client_id the alternative Material Design client id to use
+        def map_std_client_id(std_client_id, md_client_id)
+          raise ArgumentError, "Invalid standard art client id [#{std_client_id}]" unless std_client_ids.include?(std_client_id)
+          raise ArgumentError, "Invalid Material Design art client id [#{md_client_id}]" unless MDAP.has_art_client_id?(md_client_id)
+          std_client_id_map[std_client_id] = md_client_id
+        end
+
+        # @api private
+        def resolve_client_id(client_id)
+          std_client_ids.include?(client_id) ? std_client_id_map[client_id] : client_id
+        end
+
+      end
+
+      protected
+
+      def create_bitmap(id, client, size)
+        # create bundle and get bitmap from it
+        bundle = create_bitmap_bundle(id, client, size)
+        return Wx::NULL_BITMAP unless bundle.ok?
+        bmp = bundle.get_bitmap(size)
+        bmp.ok? ? bmp : Wx::NULL_BITMAP
+      end
+
+      def create_bitmap_bundle(id, client, size)
+        size = size.to_size # make sure to have a Wx::Size
+        # handle this **before** resolving the client id
+        size = MaterialDesignArtProvider.get_default_size(client) if size == Wx::DEFAULT_SIZE
+        # handle standard wxRuby3 client id mapping (if any)
+        client = MaterialDesignArtProvider.resolve_client_id(client)
+        art_path = MDAP.get_art_for(client, id)
+        return Wx::NULL_BITMAP unless art_path
+        if (art_clr = MaterialDesignArtProvider.__send__(:art_colour))
+          svg_data = change_svg_colour(File.read(art_path), art_clr)
+          Wx::BitmapBundle.from_svg(svg_data, size)
+        else
+          # create bundle
+          Wx::BitmapBundle.from_svg_file(art_path, size)
+        end
+      end
+
+      def create_icon_bundle(id, client)
+        bundle = create_bitmap_bundle(id, client, size = MaterialDesignArtProvider.get_default_size(client))
+        Wx::IconBundle.new(bundle.get_icon(size))
+      end
+
+      private
+
+      # @api private
+      FILL_RE = /fill="#(?:[0-9a-fA-F]{3,4}){1,2}"/
+      # @api private
+      PATH_RE = /<path\s/
+
+      def change_svg_colour(svg_data, colour)
+        # see if we can replace the path colours
+        rc = svg_data.gsub!(FILL_RE, "fill=\"#{colour.get_as_string(Wx::C2S_HTML_SYNTAX)}\"")
+        # if any replaced we're done
+        return svg_data if rc
+        # insert colour to every <path ...>
+        svg_data.gsub!(PATH_RE, "<path fill=\"#{colour.get_as_string(Wx::C2S_HTML_SYNTAX)}\"")
+        svg_data
+      end
+
+    end
+
+  end
+
+  # Import MaterialDesignArtProvider in Wx namespace if possible
+  MaterialDesignArtProvider = MDAP::MaterialDesignArtProvider unless Wx.const_defined?(:MaterialDesignArtProvider)
+
+end

data/lib/wx/mdap/version.rb

@@ -0,0 +1,12 @@
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+
+
+module Wx
+  module MDAP
+
+    VERSION = '1.0.0-rc.1'
+
+  end
+end

data/lib/wx/mdap.rb

@@ -0,0 +1,10 @@
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+
+
+require 'wx/core'
+
+require 'wx/mdap/version'
+require 'wx/mdap/art'
+require 'wx/mdap/provider'

data/rakelib/yard/templates/default/fulldoc/html/css/wxruby3.css

@@ -0,0 +1,91 @@
+
+div.wxrb-note {
+    background: #f7f7f9;
+    border-left: .6em solid #f3ba6f;
+    border-radius: 3px;
+    margin: 14px;
+    padding-left: 14px;
+    padding-top: 10px;
+    padding-bottom: 10px;
+}
+
+div.wxrb-remark {
+    background: #f7f7f9;
+    border-left: .6em solid #f6f4ab;
+    border-radius: 3px;
+    margin: 14px;
+    padding-left: 14px;
+    padding-top: 10px;
+    padding-bottom: 10px;
+}
+
+div.wxrb-note p,
+div.wxrb-remark p {
+    margin: 0;
+}
+
+div.wxrb-logo {
+    float: right;
+    padding-top: 12px;
+}
+
+div.wxrb-logo img {
+    vertical-align: middle;
+}
+
+div.wxrb-logo span.wxrb-name {
+    font-size: large;
+    font-weight: bold;
+    margin-left: 10px;
+}
+
+div.wxrb-logo span.wxrb-name a {
+    color: black;
+}
+
+div.wxrb-logo span.wxrb-version {
+    font-size: medium;
+    font-weight: normal;
+    margin-left: 10px;
+}
+
+div.wxrb-logo table {
+    display: inline;
+}
+
+div.wxrb-logo table td {
+    margin: 0;
+}
+
+.discussion div.note {
+    background: #f7f7f9;
+    border-left: .6em solid #f3ba6f;
+    margin: 14px;
+}
+
+.tags span.wxrb-require {
+    border-radius: 5px;
+    border: 1px solid #E1E1E8;
+    padding: 0px 3px 0px 3px;
+    background: #f3ba6f;
+    font-weight: bold;
+    font-size: 0.9em;
+}
+
+#filecontents {
+    margin-right: 340px;
+}
+
+#filecontents blockquote {
+    border-left: .5em solid #e0e0e0;
+    margin: 10px;
+    padding-left: 10px;
+}
+
+#toc {
+    position: fixed;
+    overflow-y: scroll;
+    overflow-x: hidden;
+    top: 1em;
+    bottom: 0;
+}

data/rakelib/yard/templates/default/fulldoc/html/full_list.erb

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta charset="<%= charset %>" />
+    <% stylesheets_full_list.each do |stylesheet| %>
+      <link rel="stylesheet" href="<%= mtime_url(stylesheet) %>" type="text/css" media="screen" />
+    <% end %>
+
+    <% javascripts_full_list.each do |javascript| %>
+      <script type="text/javascript" charset="utf-8" src="<%= mtime_url(javascript) %>"></script>
+    <% end %>
+
+    <title><%= @list_title %></title>
+    <base id="base_target" target="_parent" />
+  </head>
+  <body>
+    <div id="content">
+      <div class="fixed_header">
+        <%= logo_and_version %>
+        <h1 id="full_list_header"><%= @list_title %></h1>
+        <div id="full_list_nav">
+          <% menu_lists.each do |list| %>
+            <span><a target="_self" href="<%= url_for_list list[:type] %>">
+              <%= list[:title] %>
+            </a></span>
+          <% end %>
+        </div>
+
+        <div id="search">Search: <input type="text" /></div>
+      </div>
+
+      <ul id="full_list" class="<%= @list_class || @list_type %>">
+        <%= erb "full_list_#{@list_type}" %>
+      </ul>
+    </div>
+  </body>
+</html>

data/rakelib/yard/templates/default/fulldoc/html/setup.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+def init
+  # It seems YARD messes things up so that a lot of classes, modules and constants are not properly
+  # registered in their enclosing namespaces.
+  # This hack makes sure that if that is the case we fix that here.
+  all_objects = Registry.all(:class, :constant, :module, :method)
+  all_objects.each do |c|
+    if (ns = c.namespace)
+      unless ns.children.any? { |nsc| nsc.path == c.path }
+        ns.children << c # class/module/constant/method missing from child list of enclosing namespace -> add here
+      end
+    end
+    if (ns = Registry[c.namespace.path])
+      unless ns.children.any? { |nsc| nsc.path == c.path }
+        ns.children << c # class/module/constant/method missing from child list of enclosing namespace -> add here
+      end
+    end
+  end
+  super
+end
+
+def stylesheets_full_list
+  super + %w(css/wxruby3.css)
+end
+
+def logo_and_version
+  wxver = Registry['Wx::MDAP::VERSION']
+  <<~__HTML
+  <div class='wxrb-logo'>
+    <img src='art/logo.svg' height='38'/>
+    <table><tbody>
+      <tr><td><span class='wxrb-name'><a href="https://github.com/mcorino/wxRuby3-MaterialDesignArtProvider">wxRuby3 MaterialDesignArtProvider</a></span></td></tr>
+      <tr><td><span class='wxrb-version'>Version: #{::Kernel.eval(wxver.value)}</span></td></tr>
+    </tbody></table>
+  </div>
+  __HTML
+end

data/rakelib/yard/templates/default/layout/html/setup.rb

@@ -0,0 +1,5 @@
+
+def stylesheets
+  # Load the existing stylesheets while appending the custom one
+  super + %w(css/wxruby3.css)
+end

data/rakelib/yard/templates/default/tags/html/wxrb_require.erb

@@ -0,0 +1,10 @@
+<% if object.has_tag?(:wxrb_require) %>
+  <p class="tag_title">Requires:</p>
+  <ul class="wxrb-require">
+    <% wxruby_requires.each do |req| %>
+      <li><div class='inline'>
+        <%= req.join(' or ') %>
+      </div></li>
+    <% end %>
+  </ul>
+<% end %>

data/rakelib/yard/templates/default/tags/setup.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+def wxrb_require
+  erb('wxrb_require')
+end
+
+def wxruby_requires
+  object.tags(:wxrb_require).inject([]) do |list, tag|
+    tag.text.split(',').each do |feature|
+      list << feature.split('|').collect do |s|
+        s.split('&').collect { |ss| %Q[<span class="wxrb-require">#{ss.strip}</span>] }.join('&amp;')
+      end
+    end
+    list
+  end
+end

data/rakelib/yard/yard/relative_markdown_links/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module YARD
+  module RelativeMarkdownLinks
+    # Current version of the yard-relative_markdown_links gem.
+    VERSION = "0.4.1"
+  end
+end

data/rakelib/yard/yard/relative_markdown_links.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "uri"
+require "yard"
+require_relative 'relative_markdown_links/version'
+
+module YARD # rubocop:disable Style/Documentation
+  # GitHub and YARD render Markdown files differently. In particular, relative
+  # links between Markdown files that work in GitHub don't work in YARD.
+  # For example, if you have `[hello](FOO.md)` in your README, YARD renders it
+  # as `<a href="FOO.md">hello</a>`, creating a broken link in your docs.
+  #
+  # With this plugin enabled, you'll get `<a href="file.FOO.html">hello</a>`
+  # instead, which correctly links through to the rendered HTML file.
+  module RelativeMarkdownLinks
+    # Resolves relative links from Markdown files.
+    # @param [String] text the HTML fragment in which to resolve links.
+    # @return [String] HTML with relative links to extra files converted to `{file:}` links.
+    def resolve_links(text)
+      html = Nokogiri::HTML.fragment(text)
+      html.css("a[href]").each do |link|
+        begin
+          href = URI(link["href"])
+        rescue
+          return super(text)
+        end
+
+        if href.relative? && options.files
+          fnames = options.files.map(&:filename)
+          if fnames.include?(href.path)
+            link.replace "{file:#{href} #{link.inner_html}}"
+          elsif href.path.end_with?('_md.html') && (fname = fnames.find {|fnm| fnm.end_with?(href.path.sub(/_md.html\Z/, '.md')) })
+            link.replace "{file:#{fname}#{href.fragment ? "##{fragment_to_yard(href.fragment)}" : ''} #{link.inner_html}}"
+          end
+        end
+      end
+      super(html.to_s)
+    end
+
+    # this does not work with mixed case labels but is good enough for us
+    def fragment_to_yard(s)
+      s.start_with?('label-') ? s : "label-#{s.gsub('-', '+').capitalize}"
+    end
+
+  end
+
+  Templates::Template.extra_includes << RelativeMarkdownLinks
+end

data/rakelib/yard/yard-custom-templates.rb

@@ -0,0 +1,5 @@
+
+YARD::Tags::Library.define_tag("Requirements", :wxrb_require)
+YARD::Tags::Library.visible_tags.place(:wxrb_require).before(:author)
+
+YARD::Templates::Engine.register_template_path File.join(__dir__, 'templates')

data/rakelib/yard/yard-relative_markdown_links.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Adapted from the 'yard-relative_markdown_links' gem; Copyright © 2018 Andrew Haines
+
+require_relative 'yard/relative_markdown_links'

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: wxruby3-mdap
+version: !ruby/object:Gem::Version
+  version: 1.0.0.pre.rc.1
+platform: ruby
+authors:
+- Martin Corino
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-05-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: wxruby3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+description: wxRuby3/MDAP is a pure Ruby library providing a custom ArtProvider for
+  using MaterialDesign bitmaps and icons in wxRuby3
+email: mcorino@m2c-software.nl
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- Apache2.0-LICENSE
+- CC01.0-LICENSE.md
+- CCBY4.0-LICENSE
+- CREDITS.md
+- LICENSE
+- README.md
+- assets/logo.svg
+- lib/wx/mdap.rb
+- lib/wx/mdap/art.rb
+- lib/wx/mdap/provider.rb
+- lib/wx/mdap/version.rb
+- rakelib/yard/templates/default/fulldoc/html/css/wxruby3.css
+- rakelib/yard/templates/default/fulldoc/html/full_list.erb
+- rakelib/yard/templates/default/fulldoc/html/setup.rb
+- rakelib/yard/templates/default/layout/html/setup.rb
+- rakelib/yard/templates/default/tags/html/wxrb_require.erb
+- rakelib/yard/templates/default/tags/setup.rb
+- rakelib/yard/yard-custom-templates.rb
+- rakelib/yard/yard-relative_markdown_links.rb
+- rakelib/yard/yard/relative_markdown_links.rb
+- rakelib/yard/yard/relative_markdown_links/version.rb
+homepage: https://github.com/mcorino/wxRuby3-MaterialDesignArtProvider
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/mcorino/wxRuby3-MaterialDesignArtProvider/issues
+  documentation_uri: https://mcorino.github.io/wxRuby3-MaterialDesignArtProvider
+  homepage_uri: https://github.com/mcorino/wxRuby3-MaterialDesignArtProvider
+  github_repo: https://github.com/mcorino/wxRuby3-MaterialDesignArtProvider
+post_install_message: |2
+
+  wxRuby3/MDAP has been successfully installed.
+
+  Have fun using wxRuby3/MDAP.
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key: 
+specification_version: 4
+summary: wxRuby3 Material Design Art Provider
+test_files: []