(tof) 2005/07/05 Hidetoshi NAGAI This document discribes 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 >= 4, or $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). : On $SAFE >= 4, cannot call this method. 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. : On $SAFE >= 4, cannot call this method. 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. : On $SAFE >= 4, cannot call this method. 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 waring 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. : On $SAFE >= 4, cannot call this method. 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 arguemnt 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). : If $SAFE >= 4, can create a safe interpreter only. 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 $SAFE >= 4 or 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. : On $SAFE >= 4, cannot call this method. _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 arguemnt 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)