wxruby3 0.9.0.pre.beta.14 → 0.9.0.pre.rc.2

data/rakelib/lib/generate/doc/colour_dialog.yaml

@@ -0,0 +1,32 @@
+---
+:wxColourDialog:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              # Some function for redrawing using the given colour. Ideally, it
+              # shouldn't do anything if the colour is the same as the one used
+              # before.
+              # def redraw(colour) ... end
+            
+              data = Wx::ColourData.new
+              data.set_colour(initialColourToUse)
+              Wx::ColourDialog(self, data) do |dlg|
+                dlg.evt_colour_changed { |event| redraw(event.get_colour) }
+                if dlg.show_modal == Wx::ID_OK
+                   # Colour did change.
+                else
+                   # Colour didn't change.
+                end
+              end
+            
+              # This call is unnecessary under platforms generating
+              # Wx::EVT_COLOUR_CHANGED if the dialog was accepted and unnecessary
+              # under the platforms not generating this event if it was cancelled,
+              # so we could check for the different cases explicitly to avoid it,
+              # but it's simpler to just always call it.
+              redraw(data.get_colour)
+            ```

data/rakelib/lib/generate/doc/context_help_button.yaml

@@ -0,0 +1,16 @@
+---
+:wxContextHelp:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              # puts the application into a 'context-sensitive help mode' for my_window
+              context_help = Wx::ContextHelp.new(my_window)
+              ...
+              ...
+              # ends the 'context-sensitive help mode' for my_window
+              context_help.end_context_help            
+            ```

data/rakelib/lib/generate/doc/control.yaml

@@ -0,0 +1,46 @@
+---
+:wxControl.GetSizeFromTextSize:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              # Create a control for post code entry.
+              postcode = Wx::TextCtrl.new(self, ...)
+              
+              # And set its initial and minimal size to be big enough for
+              # entering 5 digits.
+              postcode.set_initial_size(
+                 postcode.get_size_from_text_size(
+                     postcode.get_text_extent("99999")))
+            ```
+
+:wxControl.GetSizeFromText:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              def get_size_from_text(text)
+                 get_size_from_text_size(get_text_extent(text))
+              end
+            ```
+
+:wxControl.SetLabelMarkup:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+
+            ```ruby
+              text = Wx::StaticText.new
+              ...
+              text.set_label_markup("<b>&amp;Bed</b> &amp;mp; "+
+                                    "<span foreground='red'>breakfast</span> "+
+                                    "available <big>HERE</big>")
+            ```

data/rakelib/lib/generate/doc/cursor.yaml

@@ -0,0 +1,40 @@
+---
+:wxCursor:
+  :detail:
+    :pre:
+      :detaileddescription:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            As with icons, cursors in X and MS Windows are created in a different manner. Therefore, separate cursors 
+            will be created for the different environments. Platform-specific methods for creating a {Wx::Cursor} object 
+            are catered for, and this is an occasion where conditional compilation will probably be required 
+            (see {Wx::Icon} for an example).
+            A single cursor object may be used in many windows (any subwindow type). The wxWidgets convention is to set 
+            the cursor for a window, as in X, rather than to set it globally as in MS Windows, although a global 
+            {set_cursor} function is also available for MS Windows use.
+            
+            === 
+            
+            Category:  Graphics Device Interface (GDI)
+            Predefined objects/pointers:
+            - {Wx::NULL_CURSOR}
+            - {Wx::STANDARD_CURSOR}
+            - {Wx::HOURGLASS_CURSOR}
+            - {Wx::CROSS_CURSOR}
+            @see Wx::Bitmap
+            @see  Wx::Icon
+            @see  Wx::Window#set_cursor
+            @see  Wx.set_cursor
+            @see  Wx::StockCursor 
+
+:wxCursor.wxCursor:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+
+            ```ruby
+              image.set_option(Wx::IMAGE_OPTION_CUR_HOTSPOT_X, hotSpotX)
+              image.set_option(Wx::IMAGE_OPTION_CUR_HOTSPOT_X, hotSpotY)
+            ```

data/rakelib/lib/generate/doc/data_object.yaml

@@ -0,0 +1,55 @@
+---
+:wxDataObjectComposite:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              class MyDropTarget < Wx::DropTarget
+            
+                def initialize
+                  dataobj = Wx::DataObjectComposite.new
+                  dataobj.add(Wx::BitmapDataObject.new, true)
+                  dataobj.add(Wx::FileDataObject.new)
+                  set_data_object(dataobj)
+                end
+              
+                def on_data(x, y, defaultDragResult)
+                  return Wx::DragNone unless get_data
+              
+                  dataobj_comp = get_data_object
+              
+                  format = dataobj_comp.get_received_format
+                  dataobj = dataobj_comp.get_object(format)
+                  case format.get_type
+                  when Wx::DataFormatId::DF_BITMAP
+                    # dataobj is Wx::BitmapDataObject
+      
+                    ... use dataobj.get_bitmap ...
+            
+                  when Wx::DataFormatId::DF_FILENAME
+                    # dataobj is Wx::FileDataObject
+      
+                     ... use dataobj->GetFilenames() ...
+            
+                  else
+                    Wx.log_error("unexpected data object format")
+                  end
+              
+                  defaultDragResult
+                end
+            
+              end
+            ```
+:wxURLDataObject:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              Wx::Clipboard.open { |clip| clip.place(Wx::URLDataObject.new(url))
+            ```

data/rakelib/lib/generate/doc/dc.yaml

@@ -0,0 +1,14 @@
+---
+:wxDC.GetSize:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+
+            ```ruby
+              sz = dc.get_dimensions
+              scaleX = (maxX.to_f / sz.width)
+              scaleY = (maxY.to_f / sz.height);
+              dc.set_user_scale([scaleX, scaleY].min,[scaleX, scaleY].min)
+            ```

data/rakelib/lib/generate/doc/dialog.yaml

@@ -0,0 +1,36 @@
+---
+:wxDialog:
+  :detail:
+    :pre:
+      :para:
+        - :pattern: !ruby/regexp /Note\s+that\s+the\s+modal\s+dialog\s+is\s+one\s+of\s+the\s+very\s+few\s+examples/
+          :replace: |
+            Note that dialogs need to be explicitly destroyed when closed and not used anymore. The traditional code for this would be like:
+      :programlisting:
+        - :pattern: !ruby/regexp /MyAskDialog.*\*dlg/
+          :replace: |
+            
+            ```ruby
+              def ask_user
+                dlg = MyAskDialog.new(...)
+                if dlg.show_modal == Wx::ID_OK
+                  # ...
+                #else: dialog was cancelled or some another button pressed
+                end  
+              
+                dlg.destroy
+              end
+            ```
+        - :pattern: !ruby/regexp /dlg\.ShowModal\(\)/
+          :replace: |
+            
+            ```ruby
+              def ask_user
+                MyAskDialog(...) do |dlg|
+                  if dlg.show_modal == Wx::ID_OK
+                    # ...
+                  #else: dialog was cancelled or some another button pressed
+                  end  
+                end
+              end
+            ```

data/rakelib/lib/generate/doc/dir_dialog.yaml

@@ -0,0 +1,25 @@
+---
+:wxDirSelector:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              dir = Wx.dir_selector('Choose a folder')
+              unless dir.empty?
+                ...
+              end
+            ```
+:wxDirDialog:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              Wx::DirDialog(nil, 'Choose input directory', '',
+                            Wx::DD_DEFAULT_STYLE | Wx::DD_DIR_MUST_EXIST)  
+            ```

data/rakelib/lib/generate/doc/event_blocker.yaml

@@ -0,0 +1,27 @@
+---
+:wxEventBlocker:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              class MyWindow
+
+                ...
+            
+                def do_something
+                  # block all events directed to this window
+                  Wx::EventBlocker.blocked_for(self) do
+                    # while we do 1000 function_that_sends_events calls 
+                    1000.times { |i| function_that_sends_events(i) }
+                  end
+                  # old event handler restored; generated event(s) from next call will be processed
+                  function_that_sends_events(0)
+                end
+
+                ... 
+            
+              end
+            ```

data/rakelib/lib/generate/doc/event_filter.yaml

@@ -0,0 +1,47 @@
+---
+:wxEventFilter:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+            # This class allows determining the last time the user has worked with
+            # this application:
+            class LastActivityTimeDetector < Wx::EventFilter
+              def initialize
+                Wx::EvtHandler.add_filter(self)
+        
+                @last = Time.now
+              end
+        
+              def clear
+                Wx::EvtHandler.remove_filter(self)
+              end
+        
+              def filter_event(event)
+                # Update the last user activity
+                t = event.get_event_type
+                case t
+                when Wx::EVT_KEY_DOWN, 
+                     Wx::EVT_MOTION, 
+                     Wx::EVT_LEFT_DOWN,
+                     Wx::EVT_RIGHT_DOWN,
+                     Wx::EVT_MIDDLE_DOWN
+                  @last = Time.now
+                end
+    
+                # Continue processing the event normally as well.
+                Event_Skip
+              end
+        
+              # This function could be called periodically from some timer to
+              # do something (e.g. hide sensitive data or log out from remote
+              # server) if the user has been inactive for some time period.
+              def is_inactive_for?(diff)
+                (Time.now - diff) > @last
+              end
+            
+            end
+            ```

data/rakelib/lib/generate/doc/events.yaml

@@ -0,0 +1,152 @@
+---
+:wxKeyEvent.GetKeyCode:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              def on_char(event)
+                 uc = event.get_unicode_key
+                 if uc
+                   # It's a "normal" character. Notice that this includes
+                   # control characters in 1..31 range, e.g. Wx::K_RETURN or
+                   # Wx::K_BACK, so check for them explicitly.
+                   if uc.ord >= 32
+                     Wx.log_message("You pressed '#{uc}'")
+                   else
+                     # It's a control character
+                     ...
+                   end
+                 else # No Unicode equivalent.
+                   # It's a special key, deal with all the known ones:
+                   case event.get_key_code
+                   when Wx::K_LEFT, Wx::K_RIGHT
+                       ... move cursor ...
+        
+                   when Wx::K_F1:
+                       ... give help ...
+                   end
+                 end
+              end
+            ```
+    :post:
+      - :pattern: !ruby/regexp /returns\s+\{Wx::K_NONE\}\)/
+        :subst: 'returns nil)'
+:wxKeyEvent.GetUnicodeKey:
+  :detail:
+    :post:
+      - :pattern: !ruby/regexp /return\s+\{Wx::K_NONE\}\./
+        :subst: 'return nil.'
+:wxKeyEvent.GetModifiers:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /ControlDown/
+          :replace: |
+            
+            ```ruby
+              if event.control_down && !event.alt_down && !event.shift_down && !event.meta_down
+                # ... handle Ctrl-XXX ...
+            ```
+        - :pattern: !ruby/regexp /GetModifiers/
+          :replace: |
+            
+            ```ruby
+              if event.get_modifiers == Wx::KeyModifier::MOD_CONTROL
+                # ... handle Ctrl-XXX ...
+            ```
+:wxMouseEvent.GetModifiers:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /ControlDown/
+          :replace: |
+            
+            ```ruby
+              if event.control_down && !event.alt_down && !event.shift_down && !event.meta_down
+                # ... handle Ctrl-XXX ...
+            ```
+        - :pattern: !ruby/regexp /GetModifiers/
+          :replace: |
+            
+            ```ruby
+              if event.get_modifiers == Wx::KeyModifier::MOD_CONTROL
+                # ... handle Ctrl-XXX ...
+            ```
+:wxUpdateUIEvent.IsCheckable:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              def on_update_ui(event)
+                ....
+                if event.is_checkable
+                  event.check(...some condition...)
+              end
+            ```
+:wxPaintEvent:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /DrawMyDocument/
+          :replace: |
+            
+            ```ruby
+              def on_paint(event)
+                self.pain do |dc|
+                   draw_my_document(dc)
+                end
+              end
+            ```
+        - :pattern: !ruby/regexp /GetViewStart/
+          :replace: |
+            
+            ```ruby
+              # Called when window needs to be repainted.
+              def on_paint(event)
+                self.paint do |dc|
+                  # Find Out where the window has scrolled to
+                  vb_pt = get_view_start # Top left corner of client
+                
+                  Wx::RegionIterator.for_region(get_update_region) do |region_it|
+            
+                    int vX,vY,vW,vH                 
+                    wxRegionIterator upd(GetUpdateRegion()) # get the update rect list
+                
+                    region_it.each do |rct|
+                      # rct == Dimensions of client area to repaint in pixels
+                
+                       # Repaint this rectangle
+                       ...some code...
+                    end
+                  end
+                end
+              end
+            ```
+:wxCloseEvent:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              def on_close(event)
+                if event.can_veto? && @file_not_saved
+                  if Wx.message_box("The file has not been saved... continue closing?",
+                                    "Please confirm",
+                                    Wx::ICON_QUESTION | Wx::YES_NO) != Wx::YES)
+                    event.veto
+                    return
+                  end
+                end
+              
+                destroy  # you may also do:  event.skip
+                         # since the default event handler does call #destroy too
+              end
+            ```

data/rakelib/lib/generate/doc/evt_handler.yaml

@@ -0,0 +1,63 @@
+---
+:wxEvtHandler.QueueEvent:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: ''
+    :post:
+      - :pattern: !ruby/regexp /This\s+implies\s+that\s+the\s+event\s+should\s+be\s+allocated\s+on\s+the\s+heap\s+and/
+        :subst: 'This implies'
+      - :pattern: !ruby/regexp /\{Wx::EvtHandler#queue_event\}.*For\s+example:/
+        :subst: ''
+      - :pattern: !ruby/regexp /Note.*problem:/
+        :subst: ''
+:wxEvtHandler.SetNextHandler:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              handlerA.set_next_handler(handlerB)
+              handlerB.set_previous_handler(handlerA)
+            ```
+:wxEvtHandler.TryBefore:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              class MyClass < BaseClass # inheriting from Wx::EvtHandler
+              ...
+              protected
+                def try_before(event)
+                  if my_pre_process(event)
+                    return true
+              
+                  super
+                end
+              end
+            ```
+:wxEvtHandler.TryAfter:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              class MyClass < BaseClass # inheriting from Wx::EvtHandler
+              ...
+              protected
+                def try_after(event)
+                  if super
+                    return true
+            
+                  my_post_process(event)
+                end
+              end
+            ```

data/rakelib/lib/generate/doc/file_dialog.yaml

@@ -0,0 +1,68 @@
+---
+:wxFileDialog:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /MyFrame::OnOpen/
+          :replace: |
+            
+            ```ruby
+            class MyFrame
+              ...
+              def on_open(event)
+                if (...current content has not been saved...)
+                  if Wx.message_box('Current content has not been saved! Proceed?', 'Please confirm',
+                                    Wx::ICON_QUESTION | Wx::YES_NO, self) == Wx::NO
+                    return 
+                  #else: proceed asking to the user the new file to open
+                  end
+                end
+              
+                Wx::FileDialog(self, "Open XYZ file", "", "",
+                                    "XYZ files (*.xyz)|*.xyz", Wx::FD_OPEN|Wx::FD_FILE_MUST_EXIST) do |dlg|
+                  return if dlg.show_modal == Wx::ID_CANCEL # the user changed idea...?
+            
+                  # proceed loading the file chosen by the user
+                  file = File.open(dlg.path, 'r') rescue nil
+                  unless file
+                     Wx.log_error("Cannot open file '#{dlg.path}'.")
+                     return
+                  end
+                  ...
+                end
+              end
+            
+            end
+            ```
+        - :pattern: !ruby/regexp /MyFrame::OnSaveAs/
+          :replace: |
+            
+            ```ruby
+            class MyFrame
+              ...
+              def on_save_as(event)
+                Wx::FileDialog(self, "Save XYZ file", "", "",
+                                    "XYZ files (*.xyz)|*.xyz", Wx::FD_SAVE|Wx::FD_OVERWRITE_PROMPT) do |dlg|
+                  return if dlg.show_modal == Wx::ID_CANCEL # the user changed idea...?
+              
+                  # save the current contents in the file
+                  begin
+                    File.open(dlg.path, 'w+') do |f|
+                      # save to file
+                    end
+                  rescue 
+                    Wx.log_error("Cannot save current contents in file '#{dlg.path}'.")
+                    return
+                  end
+                end
+                ...
+              end
+            
+            end
+            ```
+        - :pattern: !ruby/regexp /wxSystemOptions::SetOption/
+          :replace: |
+            
+            ```ruby
+              Wx::SystemOptions.set_option(Wx::OSX_FILEDIALOG_ALWAYS_SHOW_TYPES, 1)
+            ```