From: Hidetoshi NAGAI Date: 2005-04-18T18:51:48+09:00 Subject: Re: Definitive Ruby/Tk guide? Hi, From: Jeremy Bear Subject: Definitive Ruby/Tk guide? Date: Thu, 14 Apr 2005 06:59:26 +0900 Message-ID: <5b46263905041314586b31f356@mail.gmail.com> > 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 >> ============================================================================== 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) 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 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 >> ============================================================================== ---------------------------------------------------- Tcl/Tk -> Ruby/Tk ---------------------------------------------------- 'event' ['event', 'event'] <> '' ---------------------------------------------------- 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 } use 'bind_append' method use 'bind_remove' method use 'bindinfo' method (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 (nagai@ai.kyutech.ac.jp)