wxruby users - Jan 2007 - help w/push_event_handler plus doc update request

Hi,
1) Can the online api docs get updated? Specifically can the overview  
pages get added in to the main http://wxruby.rubyforge.org/doc/ 
index.html page?  I happened upon the link to the Event Overview page  
while browsing some class and wished that it had been listed in the  
Event section of the index page.I don''t know how many other  
"overview" pages there are but it doesn''t make much sense
that they
aren''t visible on the main outline page and that you only find out  
about them if you read a page on a specific item and it mentions (and  
links to ) the overview page.  I''d be happy to help out with this.


2) I am trying to figure out a best practice method of writing apps  
using wxRuby. I put the code for creating an application''s main frame  
and setting up it''s task bar icon in a separate file which I can  
require/load when I am writing a wxRuby app but I also need the  
flexibility to add event handlers to that main frame.   
push_event_handler''s name suggests it''s the way to go but I am
not
clear on how to use it.  I know that I can add the method that I want  
triggered by an event to my frame with
class << frameName
   def added_method
     ...
   end
end

but what are the specifics of making the frame-event-method connection?

I want the code to look something like what I''ve pasted below, should  
this/ could this work? I''m sorry if I''m going about his all  
backwards, but most of my Ruby experience is via writing Rails web  
apps and I''m just starting to dig in to cooking up some non-trivial  
stand alone ruby apps.

-------
#!/usr/bin/env ruby -w
#
require ''rubygems''
require ''wx''
load ''/Users/hjw/tmp/wxStff/mainframe.wrb''

class TinyApp < Wx::App
   def on_init
     frame = MainFrame.new("painter")
     setup_frame(frame)
     frame.show()
   end

   def setup_frame(frame)   # setup my application''s stuff here
     frame <----.push_event_handler here---->
     class << frame
       def on_paint
         puts ("handling on_paint")
       end #end on_paint
      end #end class<<frame
   end #end setup_frame

end #end TinyApp

TinyApp.new.main_loop

-----------------

Hi Hawley

Hawley Waldman wrote:
> can the overview   pages get added in to the main
http://wxruby.rubyforge.org/doc/ index.html page?
That sounds like a very good idea.
> I don''t know how many other  "overview" pages there are
So far I''ve written the event handling and window styles overview; some
of the html and treectrl material has been rolled into the docs for 
those classes. The WxWidgets docs come with a lot of overviews:

http://www.wxwidgets.org/manuals/2.6/wx_overviews.html#overviews

But many of these are not relevant to programming wxRuby. I would say 
the most urgent ones to add are
- an ''anatomy of the a wxruby app'' - similar to
http://wxruby.rubyforge.org/wiki/wiki.pl?Getting_Started
- a sizer overview, similar to
>  I''d be happy to help out with this.
>
>
> 2) I am trying to figure out a best practice method of writing apps  
> using wxRuby. I put the code for creating an application''s main
frame
> and setting up it''s task bar icon in a separate file which I can  
> require/load when I am writing a wxRuby app but I also need the  
> flexibility to add event handlers to that main frame.   
> push_event_handler''s name suggests it''s the way to go but
I am not
> clear on how to use it.  I know that I can add the method that I want  
> triggered by an event to my frame with
> class << frameName
>    def added_method
>      ...
>    end
> end
>
> but what are the specifics of making the frame-event-method connection?
>
> I want the code to look something like what I''ve pasted below,
should
> this/ could this work? I''m sorry if I''m going about his
all
> backwards, but most of my Ruby experience is via writing Rails web  
> apps and I''m just starting to dig in to cooking up some
non-trivial
> stand alone ruby apps.
>
> -------
> #!/usr/bin/env ruby -w
> #
> require ''rubygems''
> require ''wx''
> load ''/Users/hjw/tmp/wxStff/mainframe.wrb''
>
> class TinyApp < Wx::App
>    def on_init
>      frame = MainFrame.new("painter")
>      setup_frame(frame)
>      frame.show()
>    end
>
>    def setup_frame(frame)   # setup my application''s stuff here
>      frame <----.push_event_handler here---->
>      class << frame
>        def on_paint
>          puts ("handling on_paint")
>        end #end on_paint
>       end #end class<<frame
>    end #end setup_frame
>
> end #end TinyApp
>
> TinyApp.new.main_loop
>
> -----------------
> _______________________________________________
> wxruby-users mailing list
> wxruby-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/wxruby-users
>
>
>

Sorry, fingers fumbled onto ''send'':

Hawley Waldman wrote:
> I''d be happy to help out with this.
>   
Great.  Best way to start would be to check out the currrent subversion tree

svn checkout svn://rubyforge.org/var/svn/wxruby/trunk/wxruby2

The docs are kept in doc/textile. You''ll need rake and redcloth 
installed if you want to generate the html docs. If you wanted to add 
links to the home page to the overviews, the homepage is index.txtl. 
We''ll be very happy to receive patches or updated files for the docs on
the mailing list.
> 2) I am trying to figure out a best practice method of writing apps  
> using wxRuby. I put the code for creating an application''s main
frame
> and setting up it''s task bar icon in a separate file which I can  
> require/load when I am writing a wxRuby app but I also need the  
> flexibility to add event handlers to that main frame.   
>   
Perhaps you could say a little bit more about what you''re trying to do.
Most often you''ll want to set up the frame''s event handlers
within the
definition of your MainFrame class, within the initialize method.

More generally I''d suggest this is a good coding strategy in wxRuby - 
encapsulate the behaviours of frames and widgets (how they''re drawn,
how
they can change appearance, what information they yield, how they 
respond to events etc) within subclasses. So rather than having a 
''setup_frame'' method within App, the same work is done within
the
frame''s class definition.

If you have some behaviour you want to share between Frame types, and 
some you don''t, just create further subclasses as needed.

This approach saves a fair bit of typing referring to object instances, 
and I find it also helps tighten up the purpose and design of the UI 
elements.
> push_event_handler''s name suggests it''s the way to go but
I am not
> clear on how to use it.  
I''ve never needed to use that method - I think in almost all cases 
you''ll want to use the evt_xxx methods to set up event handlers.

They are public methods, so, coming back to your question, you can call 
them on another object to set up that frame''s event handlers; following
your example

frame = MainFrame.new(...)
# set up an event handler from outside a class
frame.evt_size { ... }
> but what are the specifics of making the frame-event-method connection?
>   
Using evt_xxx - what event are you trying to listen for?
> I want the code to look something like what I''ve pasted below,
should
> this/ could this work? 
To me it looks like that code could be a lot simpler - I''m not sure you
need all the class << frame stuff.

hth
alex

Hi Alex,

Here''s a patch for index.txtl to add the overview pages.  From what I  
saw in the svn tree I''d need to download the source for wxWidgets (or  
get the SDK, or something like that) if I wanted to help you delve  
any deeper into helping with updating / porting the docs since they  
are generated from the latex docs that are a part of wxWidgets.

-Hawley


--- index.txtl  2007-01-09 23:50:40.000000000 -0500
+++ index.txtl.new      2007-01-09 23:39:07.000000000 -0500
@@ -11,6 +11,9 @@
* There are links to C++ tutorials and topic overviews that are not
currently available in this documentation
+You can also read the "window styles overview":windowstyles.html for
some general information
+on windows styles and wxRuby constants.
+
As the wxRuby API is developed, this documentation will be updated with
Ruby-specific information.
@@ -162,6 +165,7 @@
An event object contains information about a specific event. Event
handlers blocks may optionally receive a single block parameter, which
will be an Event object of the appropriate class.
+For general information about events, see the "Event handling  
overview":eventhandlingoverview.html.
|ActivateEvent|A window or application activation event|
|CalendarEvent|Used with wxCalendarCtrl|

Hawley Waldman wrote:
> Here''s a patch for index.txtl to add the overview pages.  
Thanks very much; I''ll apply and update the online docs later today.

It''s even easier for us to apply patches submitted as attachments:
http://wxruby.rubyforge.org/wiki/wiki.pl?How_To_Create_And_Submit_Patches
> From what I  
> saw in the svn tree I''d need to download the source for wxWidgets
(or
> get the SDK, or something like that) if I wanted to help you delve  
> any deeper into helping with updating / porting the docs since they  
> are generated from the latex docs that are a part of wxWidgets.
>   
No, the wxruby docs are generated just from the textile sources in SVN. 
Only redcloth, rake and a working wxruby2 lib are needed. The classes 
listed on the rendered html home page will reflect the classes actually 
supported by your wxruby2 library.

The latex_parser is in there for reference, and so when we upgrade to 
wxWidgets 2.8.0 (and beyond) we can translate their latex docs for new 
wx classes into textile. But the latex sources aren''t needed for the 
day-to-day generation of wxruby docs.

cheers
alex

Hmmn,
Sorry I bozo''d the patch. It was late and I didn''t think that
the
mailing list would let attachments through (and I didn''t think to  
look on the site for a how-to patch).
> No, the wxruby docs are generated just from the textile sources in  
> SVN.
> Only redcloth, rake and a working wxruby2 lib are needed. The classes
> listed on the rendered html home page will reflect the classes  
> actually
> supported by your wxruby2 library.
>
> The latex_parser is in there for reference, and so when we upgrade to
> wxWidgets 2.8.0 (and beyond) we can translate their latex docs for new
> wx classes into textile. But the latex sources aren''t needed for
the
> day-to-day generation of wxruby docs.
>
But if I wanted to help get some more of the overviews ported (you  
mentioned ''anatomy'' and sizer) I''d need the latex
source?

-Hawley

> But if I wanted to help get some more of the overviews ported (you  
> mentioned ''anatomy'' and sizer) I''d need the
latex source?
>   
For those two specifically I was thinking we could adapt and update the 
already-written tutorials on the wiki. For the event handling one I 
started from scratch and just cut''n''pasted from the wxWidgets
HTML docs
as needed.

I just reviewed the wxWidgets tutorials and only a small number seem 
relevant to wxRuby:
- the overviews of control types (Dialogs);
- the info on specific controls (eg TreeCtrl) could perhaps be rolled 
into the docs for that class, if it hasn''t already been.
- drawing, fonts, bitmaps
- printing
- character conversion and i18n
- clipboard/d''n''d/dataobjects - but these aren''t yet
avail in wxruby2 anyway

but think the best place to start is with the parts of wxruby that you 
found/find unclear or confusing, and
wished there was better doc on...

thanks
alex