tk 0.1.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in tk.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,56 @@
+Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.jp>.
+You can redistribute it and/or modify it under either the terms of the
+2-clause BSDL (see the file BSDL), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or binary form,
+     provided that you do at least ONE of the following:
+
+       a) distribute the binaries and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under these terms.
+
+     For the list of those files and their copying conditions, see the
+     file LEGAL.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/MANUAL_tcltklib.eng

@@ -0,0 +1,467 @@
+(tof)
+                                    2005/07/05  Hidetoshi NAGAI
+
+This document describes about the 'tcltklib' library. Although there
+is the 'tcltk' library (tcltk.rb) under this directory, no description
+in this document (because it is not maintained recently).
+
+==============================================================
+module TclTklib
+  : Defines methods to do operations which are independed on
+  : Tcl/Tk interpreters
+
+  module TclTkLib::EventFlag
+    : Defines flags to define target events on 'do_one_event' methods.
+    : When to give, please use bit-operator (e.g. WINDOW | DONT_WAIT).
+
+    [constants]
+       NONE
+         : Is 0. It means "there is no target". But on the real
+         : operation, it is same to ALL.
+
+       WINDOW
+         : 'window' event is processed.
+
+       FILE
+         : 'file' event is processed.
+
+       TIMER
+         : 'timer' event is processed.
+
+       IDLE
+         : 'idle' operation (e.g. 're-draw'; the operations when the
+         : other kinds of events doesn't occur) is processed.
+
+       ALL
+         : All kinds of events are processed.
+         : Same to 'WINDOW | FILE | TIMER | IDLE'.
+
+       DONT_WAIT
+         : Without this flag, 'do_one_event' waits the occurrence of
+         : a target event. With this flag, doesn't wait and returns
+         : false if there is no target event for processing.
+
+  module TclTkLib::VarAccessFlag
+    : Defines flags to give '_get_variable' and so on. When to give,
+    : please use bit-operator (e.g. GLOBAL_ONLY | LEAVE_ERR_MSG ).
+
+    [constants]
+       NONE
+         : Is 0. It means "set no flag".
+
+       GLOBAL_ONLY
+         : (site Tcl/Tk's man page)
+         : Under normal circumstances the procedures look up
+         : variables as follows: If a procedure call is active
+         : in interp, a variable is looked up at the current
+         : level of procedure call. Otherwise, a variable is
+         : looked up first in the current namespace,  then  in
+         : the global namespace. However, if this bit is set
+         : in flags then the variable is looked up only in the
+         : global namespace even if there is a procedure call
+         : active. If both GLOBAL_ONLY and NAMESPACE_ONLY are
+         : given, GLOBAL_ONLY is ignored.
+         :
+         :  *** ATTENTION ***
+         : Tcl7.6 doesn't have namespaces. So NAMESPACE_ONLY
+         : is defined as 0, and then GLOBAL_ONLY is available
+         : even if flag is (GLOBAL_ONLY | NAMESPACE_ONLY).
+
+       NAMESPACE_ONLY
+         : (site Tcl/Tk's man page)
+         : Under normal circumstances the procedures look up
+         : variables as follows: If a procedure call is active
+         : in interp, a variable is looked up at the current
+         : level of procedure call. Otherwise, a variable is
+         : looked up first in the current namespace, then in
+         : the global namespace. However, if this bit is set
+         : in flags then the variable is looked up only in the
+         : current namespace even if there is a procedure call
+         : active.
+         :
+         :  *** ATTENTION ***
+         : Tcl7.6 doesn't have namespaces. So NAMESPACE_ONLY
+         : is defined as 0.
+
+       LEAVE_ERR_MSG
+         : (site Tcl/Tk's man page)
+         : If an error is returned and this bit is set in flags,
+         : then an error message will be left in the interpreter's
+         : result, where it can be retrieved with Tcl_GetObjResult
+         : or Tcl_GetStringResult. If this flag bit isn't set then
+         : no error message is left and the interpreter's result
+         : will not be modified.
+
+       APPEND_VALUE
+         : (site Tcl/Tk's man page)
+         : If this bit is set then newValue is appended to the
+         : current value, instead of replacing it. If the variable
+         : is currently undefined, then this bit is ignored.
+
+       LIST_ELEMENT
+         : (site Tcl/Tk's man page)
+         : If this bit is set, then newValue is converted to a
+         : valid Tcl list element before setting (or appending
+         : to) the variable. A separator space is appended before
+         : the new list element unless the list element is going
+         : to be the first element in a list or sublist (i.e. the
+         : variable's current value is empty, or contains the
+         : single character ``{'', or ends  in `` }'').
+
+       PARSE_VARNAME
+         : (site Tcl/Tk's man page)
+         : If this bit is set when calling _set_variable and so
+         : on, var_name argument may contain both an array and an
+         : element name: if the name contains an open parenthesis
+         : and ends with a close parenthesis, then the value
+         : between the parentheses is treated as an element name
+         : (which can have any string value) and the characters
+         : before  the first open parenthesis are treated as the
+         : name of an array variable. If the flag PARSE_VARNAME
+         : is given, index_name argument should be 'nil' since the
+         : array and element names are taken from var_name.
+         :
+         :  *** ATTENTION ***
+         : Tcl7.6 doesn't have this flag. So PARSE_VARNAME is
+         : defined as 0.
+
+  module TclTkLib::RELEASE_TYPE
+    : Defines release type number of Tcl/Tk
+
+       ALPHA
+         : ALPHA release
+
+       BETA
+         : BETA release
+
+       FINAL
+         : FINAL release
+
+  [module methods]
+     get_version()
+        : return an array of major, minor, release-type number,
+        : and patchlevel of current Tcl/Tk library.
+
+     mainloop(check_root = true)
+       : Starts the eventloop. If 'check_root' is true, this method
+       : doesn't return when a root widget exists.
+       : If 'check_root' is false, doesn't return by the other
+       : reasons than exceptions.
+
+    mainloop_thread?
+       : Returns whether the current thread executes the eventloop.
+       : If true, the eventloop is working on the current thread.
+       : If no eventloop is working, this method returns nil.
+       : And if the other thread executes the eventloop, returns false.
+       :
+       :  *** ATTENTION ***
+       : When this methods returns false, it is dangerous to call a Tk
+       : interpreter directly.
+
+    mainloop_watchdog(check_root = true)
+       : On the normal eventloop, some kinds of callback operations
+       : cause deadlock. To avoid some of such deadlocks, this
+       : method starts an eventloop and a watchdog-thread.
+
+    do_one_event(flag = TclTkLib::EventFlag::ALL |
+                          TclTkLib::EventFlag::DONT_WAIT)
+       : Do one event for processing. When processed an event,
+       : returns true.
+       : If NOT set DONT_WAIT flag, this method waits occurrence of
+       : a target event.
+       : If set DONT_WAIT flag and no event for processing, returns
+       : false immediately.
+       : If $SAFE >= 1 and the flag is tainted,
+       : force to set DONT_WAIT flag.
+
+    set_eventloop_tick(timer_tick)
+       : Define the interval of thread-switching with an integer
+       : value of mili-seconds.
+       : Default timer_tick is 0. It means that thread-switching
+       : is based on the count of processed events.
+       : ( see 'set_eventloop_weight' method )
+       : However, if the eventloop thread is the only thread,
+       : timer_tick cannot be set to 0. If 0, then is set to 100 ms
+       : automatically (see NO_THREAD_INTERRUPT_TIME on tcltklib.c).
+
+    get_eventloop_tick
+       : Get current value of 'timer_tick'
+
+    set_no_event_wait(no_event_wait)
+       : Define sleeping time of the eventloop when two or more
+       : thread are running and there is no event for processing.
+       : Default value is 20 (ms).
+       : If the eventloop thread is the only thread, this value is
+       : invalid.
+
+    get_no_event_wait
+       : Get current value of 'no_event_wait'.
+
+    set_eventloop_weight(loop_max, no_event_tick)
+       : Define the weight parameters for the eventloop thread.
+       : That is invalid when the eventloop is the only thread.
+       : 'loop_max' is the max events for thread-switching.
+       : 'no_event_tick' is the increment value of the event count
+       : when no event for processing (And then, the eventloop thread
+       : sleeps 'no_event_wait' mili-seconds).
+       : 'loop_max == 800' and 'no_event_tick == 10' are default.
+
+    get_eventloop_weight
+       : Get current values of 'loop_max' and 'no_event_tick'.
+
+    mainloop_abort_on_exception=(bool)
+       : Define whether the eventloop stops on exception or not.
+       : If true (default value), stops on exception.
+       : If false, show a warning message but ignore the exception.
+       : If nil, no warning message and ignore the exception.
+       : This parameter is sometimes useful when multiple Tk
+       : interpreters are working. Because the only one eventloop
+       : admins all Tk interpreters, sometimes exception on a
+       : interpreter kills the eventloop thread. Even if such
+       : situation, when abort_on_exception == false or nil,
+       : the eventloop ignores the exception and continue to working.
+
+    mainloop_abort_on_exception
+       : Get current status of that.
+
+    num_of_mainwindows
+       : Returns the number of main-windows (root-widget).
+       : Because there is only one main-window for one Tk interpreter,
+       : the value is same to the number of interpreters which has
+       : available Tk functions.
+
+    _merge_tklist(str, str, ... )
+       : Get a Tcl's list string from arguments with a Tcl/Tk's
+       : library function. Each argument is converted to a valid
+       : Tcl list element.
+
+    _conv_listelement(str)
+       : Convert the argument to a valid Tcl list element with
+       : Tcl/Tk's library function.
+
+    _toUTF8(str, encoding=nil)
+    _fromUTF8(str, encoding=nil)
+       : Call the function (which is internal function of Tcl/Tk) to
+       : convert to/from a UTF8 string.
+
+    _subst_UTF_backslash(str)
+    _subst_Tcl_backslash(str)
+       : Substitute backslash sequence with Tcl's rule (include \uhhhh;
+       : give a sixteen-bit hexadecimal value for Unicode character).
+       : _subst_Tcl_backslash method parses all backslash sequence.
+       : _subst_UTF_backslash method parses \uhhhh only.
+
+    encoding_system
+    encoding_system=(encoding)
+       : Get and set Tcl's system encoding.
+
+    encoding
+    encoding=(encoding)
+       : alias of encoding_system / encoding_system=
+       : ( probably, Ruby/Tk's tk.rb will override them )
+
+
+class TclTkIp
+  [class methods]
+    new(ip_name=nil, options='')
+       : Generate an instance of TclTkIp class.
+       : If 'ip_name' argument is given as a string, it is the name
+       : of the Tk interpreter which is shown by 'winfo interps'
+       : command.
+       : 'options' argument accepts a string which is the command
+       : line options of wish; such as '-geometry' or '-use'.
+       : The information is used to generate the root widget of the
+       : interpreter.
+       : ( e.g. TclTkIp.new('FOO', '-geometry 500x200 -use 0x2200009') )
+       : If is given nil or false for the 'option' argument, generates
+       : the Tcl interpreter without Tk library. Then the interpreter
+       : doesn't need GUI environment. Therefore, even if a window
+       : system doesn't exist or cannot be used, Ruby can control the
+       : Tcl interpreter and the extension libraries loaded on the
+       : interpreter.
+
+  [instance methods]
+    create_slave(name, safe=false)
+       : Create a slave interpreter.
+       : The parent of the interpreter is the receiver of this method.
+       : The name of the slave interpreter is given by 'name' argument.
+       : The 'safe' argument decides whether the slave interpreter is
+       : created as a safe interpreter or not. If true, create a safe
+       : interpreter. Default is false. However, if the parent
+       : interpreter is a safe interpreter, the created interpreter is
+       : a safe interpreter (ignore 'safe' argument value).
+
+    make_safe
+       : Make the interpreter to the safe interpreter, and returns
+       : self. If fail, raise RuntimeError.
+
+    safe?
+       : Check whether the interpreter is the safe interpreter.
+       : If is the safe interpreter, returns true.
+
+    allow_ruby_exit?
+       : Return the mode whether 'exit' function of ruby or 'exit'
+       : command of Tcl/Tk can quit the ruby process or not on the
+       : interpreter. If false, such a command quit the interpreter
+       : only.
+       : The default value for a master interpreter is true, and
+       : for a slave interpreter is false.
+
+    allow_ruby_exit=(mode)
+       : Change the mode of 'allow_ruby_exit?'.
+       : If the interpreter is a "safe" interpreter,
+       : this is not permitted (raise an exception).
+
+    delete
+       : Delete the interpreter.
+       : The deleted interpreter doesn't accept command and then
+       : raise an exception.
+
+    deleted?
+       : Check whether the interpreter is already deleted.
+       : If deleted, returns true.
+
+    has_mainwindow?
+       : Check whether the interpreter has a MainWindow (root widget).
+       : If has, returns true. If doesn't, returns false.
+       : If IP is already deleted, returns nil.
+
+    restart
+       : Restart Tk part of the interpreter.
+       : Use this when you need Tk functions after destroying the
+       : root widget.
+
+    _eval(str)
+    _invoke(*args)
+       : Estimates the arguments as a command on the Tk interpreter.
+       : The argument of _eval is a script of Tcl/Tk.
+       : Each argument of _invoke is a token of one command line of
+       : Tcl/Tk.
+       : Because the operation of _invoke doesn't through the
+       : command line parser of Tk interpreter, the cost of
+       : estimation is smaller than _eval. However, auto_load
+       : mechanism of the Tk interpreter doesn't work on _invoke.
+       : So _invoke can call only the command which already
+       : registered on the interpreter by 'load' command and so on.
+       : On _eval command, auto_load mechanism words. So if succeed
+       : to _eval and register the command once, after that, the
+       : command can be called by _invoke.
+
+    _cancel_eval(str)
+    _cancel_eval_unwind(str)
+       : (Tcl/Tk8.6 or later)
+       : Call Tcl_CancelEval() function, and cancel evaluation.
+
+    _toUTF8(str, encoding=nil)
+    _fromUTF8(str, encoding=nil)
+       : Call the function (which is internal function of Tcl/Tk) to
+       : convert to/from a UTF8 string.
+
+    _thread_vwait(var_name)
+    _thread_tkwait(mode, target)
+       : 'vwait' or 'tkwait' with thread support.
+       : The difference from normal 'vwait' or 'tkwait' command is
+       : doing independent wait from the vwait stack when they are
+       : called on the other thread than the eventloop thread.
+       : In the case of Tcl/Tk's vwait / tkwait, if 2nd vwait /
+       : tkwait is called on waiting for 1st vwait / tkwait,
+       : returns the order of [2nd]->[1st] regardless of the order
+       : of when the wait condition was fulfilled.
+       : If _thread_vwait / _thread_tkwait is called on the
+       : eventloop thread, there is no difference from vwait /
+       : tkwait. But if called on the other thread than the
+       : eventloop, stops the thread.  And when the wait condition
+       : is fulfilled, the thread restarts. The meaning of
+       : "independent from the vwait stack" is that the timing of
+       : restarting is independent from the waiting status of the
+       : other threads. That is, even if the eventloop thread is
+       : waiting by vwait and is not fulfilled the condition,
+       : _thread_vwait completes the waiting when its waiting
+       : condition is fulfilled and the thread which stopped by
+       : _thread_vwait can continue the operation.
+
+    _return_value
+       : Get the last result value on the interpreter.
+
+    _get_variable(var_name, flag)
+    _get_variable2(var_name, index_name, flag)
+       : Get the current value of a variable. If specified a
+       : index_name (see also the PARSE_VARNAME flag), get the
+       : value of the index_name element.
+
+    _set_variable(var_name, value, flag)
+    _set_variable2(var_name, index_name, value, flag)
+       : Create or modify a variable. If specified a index_name
+       : (see also the PARSE_VARNAME flag), create or modify the
+       : index_name element.
+
+    _unset_variable(var_name)
+    _unset_variable2(var_name, index_name)
+       : Remove a variable. If specified a index_name (see also
+       : the PARSE_VARNAME flag), remove the index_name element.
+
+    _get_global_var(var_name)
+    _get_global_var2(var_name, index_name)
+    _set_global_var(var_name, value)
+    _set_global_var2(var_name, index_name, value)
+    _unset_global_var(var_name)
+    _unset_global_var2(var_name, index_name)
+       : Call the associated method with the flag argument
+       : (GLOBAL_ONLY | LEAVE_ERR_MSG).
+
+    _split_tklist(str)
+       : Split the argument with Tcl/Tk's library function and
+       : get an array as a list of Tcl list elements.
+
+    _merge_tklist(str, str, ... )
+       : Get a Tcl's list string from arguments with a Tcl/Tk's
+       : library function. Each argument is converted to a valid
+       : Tcl list element.
+
+    _conv_listelement(str)
+       : Convert the argument to a valid Tcl list element with
+       : Tcl/Tk's library function.
+
+    mainloop
+    mainloop_watchdog
+       : If on the slave interpreter, never start an eventloop and
+       : returns nil.
+       : With the exception that, same to the TclTkLib module method
+       : with the same name.
+
+    do_one_event
+       : With the exception that the argument is forced to set
+       : DONT_WAIT flag on the slave interpreter, same to
+       : TclTkLib#do_one_event.
+
+    set_eventloop_tick
+    get_eventloop_tick
+    set_no_event_wait
+    get_no_event_wait
+    set_eventloop_weight
+    get_eventloop_weight
+    mainloop_abort_on_exception
+    mainloop_abort_on_exception=
+       : With the exception that it is ignored to set value on the
+       : slave interpreter, same to the TclTkLib module method with
+       : the same name.
+
+    encoding_table
+       : For Ruby m17n. Return encoding relation table between Ruby's
+       : Encoding object and Tcl's encoding name.
+
+class TkCallbackBreak < StandardError
+class TkCallbackContinue < StandardError
+  : They are exception classes to break or continue the Tk callback
+  : operation.
+  : If raise TkCallbackBreak on the callback procedure, Ruby returns
+  : 'break' code to Tk interpreter (Then the Tk interpreter will
+  : break the operation for the current event).
+  : If raise TkCallbackContinue, returns 'continue' code (Then the Tk
+  : interpreter will break the operation for the current bindtag and
+  : starts the operation for the next bindtag for the current event).
+  : However, current tcltklib supports Ruby's 'break' and 'next' to
+  : get the same effect. That is, those classes are obsolete. Those
+  : exist for backward compatibility.
+
+(eof)