wxruby3 0.9.0.pre.beta.13 → 0.9.0.pre.rc.1

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

@@ -0,0 +1,35 @@
+---
+:wxArtProvider:
+  :detail:
+    :pre:
+      :para:
+        - :pattern: !ruby/regexp /<programlisting>.*MyProvider/
+          :replace: |
+            
+            Example:
+            
+            ```ruby
+              class MyArtProvider < Wx::ArtProvider
+                
+                def create_bitmap(id, client, size)
+                  # ... create and return bitmap
+                end
+            
+              end
+            
+              Wx::ArtProvider.push(MyArtProvider.new)
+            ```
+
+        - :pattern: !ruby/regexp /Note\s+that,\s+as\s+usual\s+in\s+wxWidgets\s+API.*/
+          :replace: ''
+        - :pattern: !ruby/regexp /wxNO_IMPLICIT_WXSTRING_ENCODING/
+          :replace: ''
+      :programlisting:
+        - :pattern: !ruby/regexp /ifdef.*__WXGTK__/
+          :replace: |
+            
+            ```ruby
+              if Wx::PLATFORM == 'WXGTK'
+                bmp = Wx::ArtProvider.get_bitmap("gtk-cdrom", Wx::ART_MENU)
+              end
+            ```

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

@@ -0,0 +1,37 @@
+---
+:wxBitmap.wxBitmap:
+  :detail:
+    :pre:
+      :para:
+        - :pattern: !ruby/regexp /<programlisting>.*GetSubBitmap/
+          :replace: |
+            ```ruby
+              newBitmap = oldBitmap.get_sub_bitmap(
+                              Wx::Rect.new(0, 0, oldBitmap.width, oldBitmap.height))
+            ```
+:wxBitmapBundle:
+  :detail:
+    :pre:
+      :para:
+        - :pattern: !ruby/regexp /<programlisting>.*MyFrame::MyFrame/
+          :replace: |
+            ```ruby
+              class MyFrame < Wx::Frame
+                
+                def initialize
+                  super(nil, Wx::ID_ANY, "My frame")
+                  # ...
+                  tool_bar = create_toolBar
+               
+                  bitmaps = [
+                      Wx::Bitmap(:open_32x32, Wx::BitmapType::BITMAP_TYPE_PNG),
+                      Wx::Bitmap(:open_48x48, Wx::BitmapType::BITMAP_TYPE_PNG),
+                      Wx::Bitmap(:open_64x64, Wx::BitmapType::BITMAP_TYPE_PNG)
+                    ]
+             
+                  tool_bar.add_tool(Wx::ID_OPEN, "Open", Wx::BitmapBundle.from_bitmaps(bitmaps))
+                end
+            ```
+
+        - :pattern: !ruby/regexp /For\s+the\s+platforms\s+with\s+resources\s+support/
+          :replace: ''

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

@@ -0,0 +1,15 @@
+---
+:wxBoxSizer.AddSpacer:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /wxBoxSizer::IsVertical/
+          :replace: |
+            
+            ```ruby
+              if box_sizer.vertical?
+                box_sizer.add(0, size, 0)
+              else
+                box_size.add(size, 0, 0)
+              end
+            ```

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

@@ -0,0 +1,74 @@
+---
+:wxBusyInfo:
+  :detail:
+    :pre:
+      :detaileddescription:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            Normally the main thread should always return to the main loop to continue dispatching events as quickly as possible,
+            hence this class shouldn't be needed. However if the main thread does need to block, this class provides a simple
+            way to at least show this to the user: just call {Wx::BusyInfo.busy} with a block and for the duration of the
+            execution of the block a message window will be shown.
+            For example:
+            ```ruby
+              BusyInfo.busy('Working, please wait...') do
+                100000.times { do_a_calculation }
+              end
+            ```
+          
+            The displayed window is rather plain by default but can be customized by passing {Wx::BusyInfo.busy} an object of
+            {Wx::BusyInfoFlags} class instead of a simple message. Here is an example:
+          
+            ```ruby
+              Wx::BusyInfo.busy(
+                Wx::BusyInfoFlags.new
+                  .parent(self)
+                  .icon(Wx::ArtProvider.get_icon(Wx::ART_PRINT,Wx::ART_OTHER, [128, 128]))
+                  .title("<b>Printing your document</b>")
+                  .text("Please wait...")
+                  .foreground(Wx::WHITE)
+                  .background(Wx::BLACK)
+                  .transparency(4*Wx::ALPHA_OPAQUE/5)) do |bi|
+              end
+            ```
+          
+            This shows that separate title and text can be set, and that simple markup ({Wx::Control#set_label_markup}) can be used in them, and that it's also possible to add an icon and customize the colours and transparency of the window.
+            You may also want to call `Wx.get_app.yield` to refresh the window periodically (in case it had been obscured by other windows, for example) like this:
+            ```ruby
+              Wx::WindowDisabler.disable do
+                BusyInfo.busy('Working, please wait...') do
+                  100000.times do |i| 
+                    do_a_calculation }
+                    Wx.get_app.yield if (i % 1000) == 0
+                  end
+                end
+              end
+            ```
+          
+            but take care to not cause undesirable re-entrance when doing it (see {Wx::App#yield} for more details). The simplest way to do it is to use {Wx::WindowDisabler} class as illustrated in the above example.
+            Note that a {Wx::BusyInfo} is always built with the {Wx::STAY_ON_TOP} window style (see {Wx::Frame} window styles for more info).
+            
+            ===
+          
+            Category:  Common Dialogs
+          
+
+:wxBusyInfoFlags:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              Wx::BusyInfo.busy(
+                Wx::BusyInfoFlags.new
+                  .parent(self)
+                  .icon(Wx::ArtProvider.get_icon(Wx::ART_PRINT,Wx::ART_OTHER, [128, 128]))
+                  .title("<b>Printing your document</b>")
+                  .text("Please wait...")
+                  .foreground(Wx::WHITE)
+                  .background(Wx::BLACK)
+                  .transparency(4*Wx::ALPHA_OPAQUE/5)) do |bi|
+              end
+            ```

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

@@ -0,0 +1,19 @@
+---
+:wxClientDC:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+               # Create the initially empty label with the size big enough to show
+               # the given string.
+               text = Wx::ClientDC.draw_on(self) do |dc|
+                         Wx::StaticText.new(
+                                 self, Wx::ID_ANY, "",
+                                 Wx::Point.new,
+                                 dc.get_text_extent("String of max length"),
+                                 Wx::ST_NO_AUTORESIZE)
+                      end
+            ```

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

@@ -0,0 +1,43 @@
+---
+:wxClipboard:
+  :detail:
+    :pre:
+      :detaileddescription:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            To use the clipboard, you call member functions of the global {Wx::Clipboard} object passed to the block for {Wx::Clipboard.open}.
+            See the {Wx::DataObject} Overview for further information.
+            Call {Wx::Clipboard.open} to get ownership of the (global) clipboard and execute the given block. You now 
+            own the clipboard passed to the given block. Call {Wx::Clipboard#set_data} to put data on the clipboard, or 
+            {Wx::Clipboard#get_data} to retrieve data from the clipboard. The clipboard is closed and ownership 
+            relinquished when the block returns. You should keep the clipboard open only momentarily.
+            For example:
+            
+            ```ruby
+              # Write some text to the clipboard
+              Wx::Clipboard.open do |clip|
+                # This data object is held by the clipboard
+                clip.place(Wx::TextDataObject.new("Some text"))
+                # or alternatively
+                # clip.set_data(Wx::TextDataObject.new("Some text"))
+              end
+            
+              # Read some text
+              data = Wx::TextDataObject.new
+              Wx::Clipboard.open do |clip|
+                 if clip.supported?(Wx::DF_TEXT)
+                   clip.fetch(data) # or clip.get_data(data)
+                 end
+              end
+              Wx.message_box(data.get_text)
+            ```
+            
+            On GTK, the clipboard behavior can vary depending on the configuration of the end-user's machine. In order 
+            for the clipboard data to persist after the window closes, a clipboard manager must be installed. Some 
+            clipboard managers will automatically flush the clipboard after each new piece of data is added, while others 
+            will not. The {Wx::Clipboard#flush} function will force the clipboard manager to flush the data.
+            
+            === 
+            
+            Category:  Clipboard and Drag & Drop
+            @see  Wx::DataObject 

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

@@ -0,0 +1,21 @@
+---
+:wxCollapsiblePane:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              collpane = Wx::CollapsiblePane.new(self, Wx::ID_ANY, "Details:")
+              
+              # add the pane with a zero proportion value to the 'sz' sizer which contains it
+              sz.add(collpane, 0, Wx::GROW|Wx::ALL, 5)
+              
+              #/ now add a test label in the collapsible pane using a sizer to layout it:
+              win = collpane.get_pane
+              pane_sz = Wx::VBoxSizer
+              pane_sz.add(Wx::StaticText.new(win, Wx::ID_ANY, "test!"), 1, Wx::GROW|Wx::ALL, 2)
+              win.set_sizer(pane_sz)
+              pane_sz.set_size_hints(win)
+            ```

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/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/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
+            ```