Hi,
From: Jeremy Bear <
[email protected]>
Subject: Definitive Ruby/Tk guide?
Date: Thu, 14 Apr 2005 06:59:26 +0900
Message-ID: said:
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
ption_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)
aned 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
val
TkcPolygon
olygon
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
hoto 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:
riority :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'
==============================================================================
