Re: Definitive Ruby/Tk guide?

Hi, 

From: Jeremy Bear <[e-mail]>
Subject: Definitive Ruby/Tk guide?
Date: Thu, 14 Apr 2005 06:59:26 +0900
Message-ID: <[e-mail]>
>                   Is there a definitive Ruby/Tk guide or piece of
> documentation out there that I'm unaware of?

Can the following help you?
-----------------------------------------------
<< Classes and Modules of Ruby/Tk >>
==============================================================================
   <Class>
   TclTkIp   :[tcltklib] Tcl/Tk interpreter

   MultiTkIp   :treat multiple Tcl/Tk interpreters
     RemoteTkIp  :control other Tk (Tcl/Tk or Ruby/Tk) interpreters on other 
                  processes by Tcl/Tk's 'send' command. (When its own window 
                  and the other's window exist on a same display and the 
                  others accept 'send' command control, the process of the 
                  other can be controlled even if the process exists on the 
                  another machine.)

   TkKernel
     TkObject
       TkWindow
         TkRoot   :root widget

         TkToplevel   :toplevel widget

         TkFrame  :frame widget
           TkLabelFrame  :frame widget with label
           TkMenubar     :menubar frame

         TkLabel  :label widget
           TkMessage   :message widget

           TkEntry   :entry widget
             TkSpinbox   :spinbox widget

           TkButton   :button widget
             TkRadioButton (TkRadiobutton)   :radiobutton widget
               TkCheckButton (TkCheckbutton)   :checkgutton widget

           TkMenubutton   :menubutton widget
             TkOptionMenubutton  :option_menu_button
                                  (use Tcl/Tk's 'tk_optionMenu' command)

         TkTextWin
           TkListbox   :listbox widget
             TkScrollbox   :listbox widget with scrollbar
           TkText   :text widget

         TkCnavas  :canvas widget

         TkMenu   :menu widget
           TkMenuClone       :clone menu
           TkSysMenu_Help    :system-dependent 'Help' menu (Unix)
           TkSysMenu_System  :system-dependent 'System' menu (Windows)
           TkSysMenu_Apple   :system-dependent 'Apple' menu (Mac)
           TkOptionMenubutton::OptionMenu  :menu allocated option_menu_button

         TkPanedWindow (TkPanedwindow)   :paned window widget

         TkScale   :scale widget

         TkScrollbar  :scrollbar widget
           TkXScrollbar   :horizontal scrollbar
           TkYScrollbar   :vertical scrollbar

         TkDialog2   :dialog (reusable)
           TkDialog     :dialog (disposal)
           TkWarning2   :dialog for warning (reusable)
             TkWarning    :dialog for warning (disposal)


       TkcItem   :canvas item class (abstract class)
         TkcArc         :arc
         TkcBitmap      :bitmap
         TkcImage       :image
         TkcLine        :line
         TkcOval        :oval
         TkcPolygon     :polygon
         TkcRectangle   :rectangle
         TkcText        :text
         TkcWindow      :embedded window

       TkcTag  :canvas tag
         TkcTagString   :canvas tag which has given name
         TkcTagAll      :'all' tag
         TkcTagCurrent  :'current' tag
         TkcGroup       :tag group (treat a set of tags)

       TkImage   :Image object (abstract class)
         TkBitmapImage   :bitmap
         TkPhotoImage    :photo image

       TkTextTag   :text tag
         TkTextNamedTag   :text tag which has given name
           TkTextTagSel   :'sel' tag

       TkTextMark   :text mark
         TkTextNamedMark    :text mark which has given name
           TkTextMarkInsert   :'insert' mark
           TkTextMarkCurrent  :'current' mark
           TkTextMarkAnchor   :'anchor' mark

       TkTextImage   :image object on text widget

       TkTextWindow   :embedded widget on text widget

       TkNamespace   :namespace on Tcl/Tk
       TkNamespace::NsCode   :namespace binding

       TkMsgCatalog  :message catalog


     TkUtil::CallbackSubst   :admin '%' substitution on callback
       Tk::Event   :for event callback
       TkValidateCommand::ValidateArgs   :for validation of entry widget
       TkSpinbox::ValidateArgs   :for validation of spinbox widget

     TkUtil::CallbackSubst::Info :[internal use](used by TkUtil::CallbackSubst)

     TkCallbackEntry   :callback object


   TkFont   :font object
     DescendantFont   :descendant font (Japanized Tk8.0 only)

   TkTimer (TkAfter)   :timer object

   TkBindTag   :bindtag
     TkBindTagAll   :'all' bindtag
     TkDatabaseClass   :database class bindtag (or bindtag with given name).
                        see 'class' option ('classname' option on Ruby/Tk) of 
                        frame widget

   TkValidateCommand   :validation command (callback with '%' substituteion)
     TkSpinbox::SpinCommand :for command option of spinbox widget

   String
     Tk::EncodedString   :string with encoding information
       Tk::BinaryString   :binary string
       Tk::UTF8_String    :utf-8 string

   Array
     TkNamespace::ScopeArgs   :[internal use](used by namespace binding)

   Hash
     Tk::OptionObj   :admin options of multiple widgets

   Exception
     StandardError
       TkCallbackReturn    :send 'return' code to Tcl/Tk interpreter
       TkCallbackBreak     :send 'break' code to Tcl/Tk interpreter
       TkCallbackContinue  :send 'continue' code to Tcl/Tk interpreter
     MultiTkIp_OK   :[internal use] (used by MultiTkIp)


   <Module>
   TclTkLib   :[tcltklib] utility methods for Tcl/Tk libraries
   TclTkLib::EventFlag   :event-flag constants for eventloop
   TclTkLib::VarAccessFlag  :access-flag constants for Tcl/Tk variables
   TkUtil   :utility methods for Ruby/Tk (defined with C)
   TkComm   :utility methods for Ruby/Tk (defined with Ruby)
   TkCore   :treat interaction between Ruby and Tcl/Tk interpreter
   Tk  :main module of Ruby/Tk
   Tk::Encoding   :encoding setting
   TkBindCore     :core module of treating bind
   TkTreatFont    :methods to treat font option of widgets
   TkConfigMethod   :methods to treat widget options
   TkBgError   :wrapper of Tcl/Tk's 'bgerror' command
   TkCanvasItemConfig   :methods to treate options of canvas items
   TkcTagAccess   :methods to treat canvas tags
   TkClipboard   :wrapper of Tcl/Tk's 'clipboard' command
   Tk::Clock   :wrapper of Tcl/Tk's 'clock' command
   TkComposite   :module to help creating a composite widget class
   TkConsole   :wrapper of Tcl/Tk's 'console' command
   TkEvent   :methods to setup bindings for widgets
   TkEvent::Event::TypeNum   :definitions of event-type constants
   TkGrid   :methods for 'grid' geometry manager
   TkItemConfigOptkeys   :definitions of option types of widget items
   TkItemConfigMethod   :methods to treat options of widget items
   TkItemFontOptkeys   :definitions of keys for font options of widget items
   TkTreatItemFont   :methods to treat font options of widget items
   TkKinput   :control IM 'kinput2'
   TkListItemConfig   :methods to treat options of listbox items
   TkMacResource   :treat Macintosh resources
   TkMenuEntryConfig   :methods to treat options of menu entries
   TkSystemMenu   :to define a system dependent menu class
   TkMenuSpec   :module to define a menu structure
   TkManageFocus   :wrapper of Tcl/Tk's utility commands to admin focus
   TkOptionDB   :module to treat option database
   TkOptionDB::Priority   :definition of priority constants of option database
   TkPack   :methods for 'pack' geometry manager
   TkPackage   :treat Tcl/Tk's packages
   TkPalette  :treat Tcl/Tk's color palette
   TkPlace   :methods for 'place' geometry manager
   Tk::Scrollable   :methods for scrollable widgets
   Tk::X_Scrollable   :methods for horizontal scrollable widgets
   Tk::Y_Scrollable   :methods for vertical scrollable widgets
   TkSelection   :wrapper of Tcl/Tk's 'selection' command
   TkTreatTagFont   :methods to treat font option of text tags
   Tk::ValidateConfigure   :to treat widget options with '%' substitution
   Tk::ItemValidateConfigure   :to treat item options with '%' substitution
   TkValidation   :module to treat options for validation and so on
   TkValidation::ValidateCmd::Action   :action type constants for validation
   TkWinfo   :methods to get window information (for Tcl/Tk's 'winfo' command)
   TkWinDDE  :module for Dynamic Data Exchange command (Windows only)
   TkWinRegistry  :treat registry of Windows OS
   Tk::Wm   :cooperation with window manager
   TkXIM   :treat input methods
==============================================================================

<< Create a widget >>
==============================================================================
Standard form::

  widget_class.new(parent, arg, ..., options){ ... }

    parent   :: parent widget ( if nil, denotes the root widget )
    arg, ... :: widget dependent arguments ( if required )
    options  :: a hash { option_name => value, ... }
                ( option_name is a string or a symbol )

    the block is evaled by widget_class#instance_eval method

Options and block::
  Apply options at widget creation, and next, eval the block.
  Some widget options must be given by options argument.
  (e.g. 'container' option of TkFrame widget. )
==============================================================================

<< How to set widget options >>
==============================================================================
configure(options)   :: options is a hash {opt=>val, ... }. returns self.
configure(option,val):: option is a string or a symbol. returns self.
option_name(val)     :: if option_name method is not defined. returns self.
option_name = val    :: if option_name method is not defined. returns val.
[option_name] = val  :: same to configure(option, val)

  e.g. When want to set the text option of a widget w to 'foo', 
         w.configure(:text=>'foo)  or  w.configure('text'=>'foo')
         w.text('foo')
         w.text = 'foo'              and so on.
==============================================================================

<< How to get widget options >>
==============================================================================
cget(option)       :: return current value of the option (a string or a symbol)
configinfo         :: return a array of array [option_name, database_name, 
                      database_class, default_value, current_value]
configinfo(option) :: return a array [option, database_name, database_class, 
                      default_value, current_value]
current_configinfo :: a hash {option=>current_value, ....}
current_configinfo(option) :: a hash {option=>current_value}
option_name        :: same to cget(option_name)
[option_name]      :: if [] method is not defined, same to cget(option_name)

  e.g. When want to get the text option of a widget w,
         w.cget(:text)  or  w.cget('text')
         search on return value of w.configinfo()
         w.configinfo(:text)  or  w.configinfo('text')
         search on return value of w.current_configinfo
         w.current_configinfo(:text)  or  w.current_configinfo('text')
         w.text
         w[:text]  or w['text']
==============================================================================

<< How to use man pages of Tcl/Tk >>
==============================================================================
 [Example]
     [Tcl/Tk] man page of label widget
     ------------------------------------------------------------------
     NAME
            label - Create and manipulate label widgets

     SYNOPSIS
            label pathName ?options?

     STANDARD OPTIONS
            -anchor       -font                  -image     -takefocus
            -background   -foreground            -justify   -text
            -bitmap       -highlightbackground   -padx      -textvariable
            -borderwidth  -highlightcolor        -pady      -underline
            -cursor       -highlightthickness    -relief    -wraplength

            See  the  options manual entry for details on the standard
            options.

     WIDGET-SPECIFIC OPTIONS
            Command-Line Name:-height
            Database Name:  height
            Database Class: Height

                   Specifies a desired height for the  label.   If  an
                   image  or  bitmap  is  being displayed in the label
                   then the value is in screen units (i.e. any of  the
                   forms  acceptable  to Tk_GetPixels); for text it is
                   in lines of text.  If this option isn't  specified,
                   the  label's  desired  height  is computed from the
                   size of the image or bitmap or text being displayed
                   in it.
     ------------------------------------------------------------------

     [Ruby/Tk] class definition of label widget
     ------------------------------------------------------------------
     class TkLabel<TkWindow
       TkCommandNames = ['label'.freeze].freeze
       WidgetClassName = 'Label'.freeze
       WidgetClassNames[WidgetClassName] = self
       #def create_self(keys)
       #  if keys and keys != None
       #    tk_call_without_enc('label', @path, *hash_kv(keys, true))
       #  else
       #    tk_call_without_enc('label', @path)
       #  end
       #end
       #private :create_self

       def textvariable(v)
         configure 'textvariable', tk_trace_variable(v)
       end
     end
     ------------------------------------------------------------------

     +-->  SYNOPSIS :: command format of widget creation
     |       * 'label' is a command name on the label widget
     |
     +-->  general definition of Ruby/Tk's widget class
             * defined by 'TkCommandNames' array
             * call Tcl/Tk interpreter in 'create_self' method
               ( by default, use TkCommandNames[0] )

     +--> definitions of Tcl/Tk widget options
     |      a set of 'Command-Line Name', 'Database Name', and 'Database Class'
     |
     |      e.g. '-height' option
     |             Command-Line Name:-height
     |             Database Name:  height
     |             Database Class: Height
     |
     |      define '-height' option and '-text' option on the command line
     |        label parent.myName -height val -text val
     |           ==> use 'Command-Line Name'.
     |               'parent' is the path of the parent widget.
     |               'myName' is the name of the label widget.
     |                  --> 'parent.myName' is the full path name of the widget
     |
     *--> on Ruby/Tk
            give options by a hash
              TkLabel.new(parent, :height=>val, :text=>val)
                 or
              TkLabel.new(parent, 'height'=>val, 'text'=>val)

                --> 'parent' is a parent widget object.
                    no need to give the name of the label widget.
                    ( can define the name by 'widgetname' key on the hash )
==============================================================================

<< Default rule of converting values from Ruby to Tk >>
==============================================================================
String  -> as is (usually convert encoding of the string).
Symbol  -> to string
Numeric -> to string
Array   -> to a list string of Tcl/Tk
Hash    -> convert to [-key, value, -key, value, ...] by TkComm.hash_kv()
TkUtil::None -> a special object. removed from arguments.

( Please try TkComm._get_eval_string() or TkComm.hash_kv(). )

==============================================================================

<< TclTkIp#_invoke and TclTkIp#_eval >>
==============================================================================
_invoke(*args) : treat each arguemnt as a token of Tcl/Tk's command line.
                  --> not use Tcl/Tk's command line parser.

_eval(string)  : eval the string on Tcl/Tk.
                  --> use Tcl/Tk's command line parser.

 NOTE:: Some Tcl/Tk's commands which loaded by 'autoload' facility must be 
        called by _eval method, because the facility works on the command 
        line parser. 

==============================================================================

<< Tk.tk_call and Tk.tk_send >>
==============================================================================
wrappers of TclTkIp#_invoke

tk_call(*args) : convert arguments and cal TkCore::INTERP._invoke
tk_send(*args) : convert arguments and add self as the 1st argument
                  and cal TkCore::INTERP._invoke

 NOTE:: TkCore::INTERP is a default interpreter created when "requrie 'tk'"

Usually convert encoding when Ruby->Tk and Tk->Ruby.
If want to call without converting encoding, use tk_call_without_enc().
==============================================================================

<< Utility methods on TkComm module >>
==============================================================================
tk_tcl2ruby(str) : estimate the pattern of str and convert to an object

_at(x,y=nil) : convert to "@x,y" or "@x" (index string of some wiget classes)

tk_split_list(val) : convert a Tcl/Tk's list string to a Ruby's array, 
                     and convert each element to an object. 
                     If an element seems like a list, call recursively.

tk_split_simplelist(val) : convert a Tcl/Tk's list string to a Ruby's array 
                           of strings (not call recursively). 

array2tk_list(ary) : convert a Ruby's array to a Tcl/Tk's list string

_symbolkey2str(hash) : return new hash which convert each key to a string

hash_kv(hash) : convert {key=>val, ...} to ['-key', val, ... ]

bool(str) : convert to true/false as if the str is a Tcl/Tk's boolean value.

number(str) : convert to a Numeric as if the str is a Tcl/Tk's numeric value.

string(str) : as is, however, if the str is wrapped by { }, remove { }

num_or_str(str) : if the str is assumed a Tcl/Tk's numeric value, 
                  return a numeric object, else return string(str).

list(str) : same to tk_split_list(str)

simplelist(str) : same to tk_split_simplelist(str)

window(str) : return a widget object as if the str is a widget path

procedure(str) : return proc object as if the str is a command string for a 
                 entried callback procedure.

_toUTF8(str, enc=nil) : convert encoding of the str from enc to utf-8
                        ( if enc == nil, use default encoding )

_fromUTF8(str, enc=nil) : convert encoding of the str from utf-8 to enc
                        ( if enc == nil, use default encoding )

_get_eval_string(obj) : convert obj to a string to pass to Tcl/Tk interpreter

install_cmd(cmd) : entries the cmd as a callback procedure, and returns
                   a command string to pass to Tcl/Tk interpreter
==============================================================================

<< Binding >>
==============================================================================
<Event sequence>
     ----------------------------------------------------
             Tcl/Tk         ->         Ruby/Tk
     ----------------------------------------------------
             <event>                   'event'
         <event><event>            ['event', 'event']
        <<virtual-event>>          '<virtual-event>'
     ----------------------------------------------------

<Define bind>
   target.bind(event-sequence, procedure)
       or
   target.bind(event-sequence, procedure){ procedure }
       or
   target.bind(event-sequence, procedure, arg, arg, ... )
       or
   target.bind(event-sequence, arg, arg, ... ){ procedure }

<Append bind>
   use 'bind_append' method

<Remove bind>
   use 'bind_remove' method

<Get bind information>
   use 'bindinfo' method

<Information of evnet>
   (1) without arguments --> get an event object
         e.g.  proc{|ev| ... }
                 ev.widget : the widget which get the event
                 ev.x : x coords on the widget
                 ev.y : y coords on the widget
                 ev.x_root : x coords on the full window
                 ev.y_root : y coords on the full window
                 ev.char : a character of the pressed key on the keyboard
                 ev.keysym : a key-symbol of the pressed key on the keyboard
               and so on.

   (2) with arguments  -->  get defined arguments with substitution
            ( if an argument string includes spaces, each of splited string is 
              treated as an argument. )

           * '%' + 1 char in the argument --> do '%' substitution, if available

           * '%' + 1 char --> do '%' substitution, if available.
                              And returns as a proper object.
                                %W == ev.widget
                                %x == ev.x
                                %y == ev.y   and so on.

           * others --> a string

         e.g.  proc{|a,b,c,d,e| ... }, '%W', 'x%W', '%x %y', 123
                  a == the widget which get the event
                  b == 'x' + the path of the widget
                  c == x coords on the widget
                  d == y coords on the widget
                  e == a string '123'
==============================================================================
-- 
Hidetoshi NAGAI ([e-mail])