Merge pull request #483 from mcorino/develop

add Help sample and test

Author: mcorino

lib/wx/core/context_help.rb

@@ -0,0 +1,17 @@
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+
+module Wx
+
+  class << self
+
+    define_method :ContextHelp do |window = nil|
+
+      context_help(window)
+
+    end
+
+  end
+
+end

lib/wx/core/helpcontrollerhelpprovider.rb

@@ -12,17 +12,25 @@
 require_relative './simplehelpprovider'
 
 class Wx::HelpControllerHelpProvider < Wx::SimpleHelpProvider
-  def initialize(help_controller)
+  def initialize(help_controller = nil)
     super()
     @hc = help_controller
   end
 
+  def get_help_controller
+    @hc
+  end
+
+  def set_help_controller(help_controller)
+    @hc = help_controller
+  end
+
   # Show help for +win+; if the help text for +win+ is a string with a
   # single integer only, treats that as a section id for help and shows
   # that, otherwise shows a popup (native-style on Windows) of the text.
   def show_help(win)
     help_text = get_help(win)
-    return false if help_text.empty?
+    return false if help_text.empty? || @hc.nil?
     if help_text =~ /\A\d+\z/
       @hc.display_context_popup(help_text.to_i)
     else

lib/wx/doc/context_help.rb

@@ -0,0 +1,42 @@
+# :stopdoc:
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+# :startdoc:
+
+
+module Wx
+
+  # This method changes the cursor to a query and puts the application into a 'context-sensitive help mode'.
+  #
+  # When the user left-clicks on a window within the specified window, a Wx::EVT_HELP event is sent to that control,
+  # and the application may respond to it by popping up some help.
+  # The method returns after the left-click.
+  #
+  # For example:
+  #
+  # ```ruby
+  #   Wx.context_help(myWindow)
+  # ```
+  #
+  # There are a couple of ways to invoke this behaviour implicitly:
+  #
+  # - Use the Wx::DIALOG_EX_CONTEXTHELP style for a dialog (WXMSW only). This will put a question mark in the titlebar,
+  #   and Windows will put the application into context-sensitive help mode automatically, without further programming.
+  # - Create a Wx::ContextHelpButton, whose predefined behaviour is to create a context help object. Normally you will
+  #   write your application so that this button is only added to a dialog for non-Windows platforms (use
+  #   Wx::DIALOG_EX_CONTEXTHELP on WXMSW).
+  #
+  # Note that on macOS, the cursor does not change when in context-sensitive help mode.
+  #
+  # @param [Wx::Window] window  the window which will be used to catch events; if nullptr, the top window will be used.
+  # @return [void]
+  def self.context_help(window = nil); end
+
+  # Convenience alias for {Wx.context_help} similarly named as the wxWidgets wxContextHelp class.
+  #
+  # @param [Wx::Window] window  the window which will be used to catch events; if nullptr, the top window will be used.
+  # @return [void]
+  def self.ContextHelp(window = nil); end
+
+end

lib/wx/doc/html/html_help_controller.rb

@@ -9,14 +9,36 @@ module Wx
 
   module HTML
 
-    class HelpController
+    class HtmlHelpController
 
       # Returns the latest frame size and position settings and whether a new frame is drawn with each invocation.
       # @return [Array(Wx::Frame,Wx::Size,Wx::Point,Boolean)] latest frame settings
       def get_frame_parameters; end
 
     end
 
+    # This module method uses Wx::HTML::HtmlHelpController to display help in a modal dialog and returns after
+    # the dialog has been closed.
+    #
+    # This is useful on platforms such as WXOSX where if you display help from a modal dialog, the help window must
+    # itself be a modal dialog.
+    #
+    # @param [Wx::Window] parent parent of the dialog.
+    # @param [String] help_file the HTML help file to show.
+    # @param [String] topic an optional topic. If this is empty, the help contents will be shown.
+    # @param [Integer] style is a combination of the flags described in the {Wx::HTML::HtmlHelpController} documentation.
+    # @return [void]
+    def self.html_modal_help(parent, help_file, topic = '', style = Wx::HTML::HF_DEFAULT_STYLE); end
+
+    # Convenience alias for {Wx::HTML.html_modal_help} similarly named as the wxWidgets wxHtmlModalHelp class.
+    #
+    # @param [Wx::Window] parent parent of the dialog.
+    # @param [String] help_file the HTML help file to show.
+    # @param [String] topic an optional topic. If this is empty, the help contents will be shown.
+    # @param [Integer] style is a combination of the flags described in the {Wx::HTML::HtmlHelpController} documentation.
+    # @return [void]
+    def self.HtmlModalHelp(parent, help_file, topic, style = Wx::HTML::HF_DEFAULT_STYLE); end
+
   end
 
 end

lib/wx/html/htmlhelpcontroller.rb

@@ -27,6 +27,16 @@ def self.instance(*args)
 
     end
 
+    class << self
+
+      define_method :HtmlModalHelp do |parent, help_file, topic = '', style = Wx::HTML::HF_DEFAULT_STYLE|
+
+        html_modal_help(parent, help_file, topic, style)
+
+      end
+
+    end
+
   end
 
 end

rakelib/lib/director/context_help_button.rb

@@ -16,8 +16,41 @@ class ContextHelpButton < Button
 
       def setup
         super
-        spec.items << 'wxContextHelp'
-        spec.no_proxy 'wxContextHelp'
+        # add custom implementation of ContextHelp as module function (not a class)
+        spec.add_header_code <<~__CODE
+          SWIGINTERN int SWIG_AsVal_bool (VALUE obj, bool *val); // forward decl
+
+          static VALUE wxruby_ContextHelp(int argc, VALUE *argv, VALUE self)
+          {
+            if (argc > 1)
+            {
+              rb_raise(rb_eArgError, "wrong # of arguments %d for 1", argc);
+              return Qnil;
+            }
+
+            void *ptr = nullptr;
+            wxWindow *window = nullptr;
+            int res = 0;
+          
+            if (argc > 0)
+            {
+              res = SWIG_ConvertPtr(argv[0], &ptr, SWIGTYPE_p_wxWindow, 0);
+              if (!SWIG_IsOK(res)) 
+              {
+                VALUE msg = rb_inspect(argv[0]);
+                rb_raise(rb_eTypeError, "expected wxWindow* for 1 but got %s", StringValuePtr(msg));
+                return Qnil; 
+              }
+              window = reinterpret_cast< wxWindow * >(ptr);
+            }
+
+            wxContextHelp(window, true);
+            return Qnil;
+          } 
+          __CODE
+        spec.add_init_code <<~__CODE__
+          rb_define_module_function(mWxCore, "ContextHelp", VALUEFUNC(wxruby_ContextHelp), -1);
+          __CODE__
       end
     end # class ContextHelpButton
 

rakelib/lib/director/help_controller.rb

@@ -21,15 +21,20 @@ def setup
         spec.rename_for_ruby('Init' => "#{spec.module_name}::Initialize")
         # ignore these (pure virtual) decls
         spec.ignore %w[
+          wxHelpControllerBase::DisplayContents
           wxHelpControllerBase::DisplayBlock
           wxHelpControllerBase::DisplaySection
+          wxHelpControllerBase::KeywordSearch
           wxHelpControllerBase::LoadFile
           wxHelpControllerBase::Quit
-          ]
+          ], ignore_doc: false
         # and add them as the implemented overrides they are
         spec.extend_interface spec.module_name,
+                              'virtual bool DisplayContents()',
                               'virtual bool DisplayBlock(long blockNo)',
                               'virtual bool DisplaySection(int sectionNo)',
+                              'virtual bool DisplaySection(const wxString &section)',
+                              'virtual bool KeywordSearch(const wxString &keyWord, wxHelpSearchMode mode=wxHELP_SEARCH_ALL)',
                               'virtual bool LoadFile(const wxString &file=wxEmptyString)',
                               'virtual bool Quit()'
         # ignore this problematic method
@@ -62,11 +67,74 @@ def setup
           spec.ignore 'wxHtmlHelpController::CreateHelpFrame',
                       'wxHtmlHelpController::CreateHelpDialog',
                       'wxHtmlHelpController::GetFrame',
-                      'wxHtmlHelpController::GetDialog'
+                      'wxHtmlHelpController::GetDialog',
+                      'wxHtmlHelpController::DisplayContents',
+                      'wxHtmlHelpController::KeywordSearch'
+          # add custom implementation of HtmlModalHelp as module function (not a class)
+          spec.add_header_code <<~__CODE
+            static VALUE wxruby_HtmlModalHelp(int argc, VALUE *argv, VALUE self)
+            {
+              if (argc < 2 || argc > 4)
+              {
+                rb_raise(rb_eArgError, "wrong # of arguments %d for 2 (max 4)", argc);
+                return Qnil;
+              }
+
+              void *ptr = nullptr;
+              wxWindow *parent = nullptr;
+              wxString help_file;
+              wxString topic = wxEmptyString;
+              int style = wxHF_DEFAULT_STYLE;
+              int res = 0;
+            
+              res = SWIG_ConvertPtr(argv[0], &ptr, SWIGTYPE_p_wxWindow, 0);
+              if (!SWIG_IsOK(res)) 
+              {
+                VALUE msg = rb_inspect(argv[0]);
+                rb_raise(rb_eTypeError, "expected wxWindow* for 1 but got %s", StringValuePtr(msg));
+                return Qnil; 
+              }
+              parent = reinterpret_cast< wxWindow * >(ptr);
+              if (TYPE(argv[1]) != T_STRING)  
+              {
+                VALUE msg = rb_inspect(argv[1]);
+                rb_raise(rb_eTypeError, "expected String for 2 but got %s", StringValuePtr(msg));
+                return Qnil;
+              }
+              help_file = RSTR_TO_WXSTR(argv[1]);
+              if (argc > 2)
+              {
+                if (TYPE(argv[2]) != T_STRING)  
+                {
+                  VALUE msg = rb_inspect(argv[2]);
+                  rb_raise(rb_eTypeError, "expected String for 3 but got %s", StringValuePtr(msg));
+                  return Qnil;
+                }
+                topic = RSTR_TO_WXSTR(argv[2]);
+              }
+              if (argc > 3)
+              {
+                if (TYPE(argv[3]) != T_FIXNUM)  
+                {
+                  VALUE msg = rb_inspect(argv[3]);
+                  rb_raise(rb_eTypeError, "expected Integer for 4 but got %s", StringValuePtr(msg));
+                  return Qnil;
+                }
+                style = NUM2INT(argv[3]);
+              } 
+              wxHtmlModalHelp(parent, help_file, topic, style);
+              return Qnil;
+            } 
+            __CODE
+          spec.add_init_code <<~__CODE__
+            rb_define_module_function(mWxHtmlHelpController, "HtmlModalHelp", VALUEFUNC(wxruby_HtmlModalHelp), -1);
+            __CODE__
         elsif spec.module_name == 'wxExtHelpController'
           spec.ignore %w[
+            wxExtHelpController::DisplayContents
             wxExtHelpController::DisplayBlock
             wxExtHelpController::DisplaySection
+            wxExtHelpController::KeywordSearch
             wxExtHelpController::LoadFile
             wxExtHelpController::Quit
             wxExtHelpController::GetFrameParameters