зеркало из https://github.com/github/ruby.git
474 строки
19 KiB
Plaintext
474 строки
19 KiB
Plaintext
(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 taget events on 'do_one_event' methos.
|
|
: 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 occurence 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, doen'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 cannt 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 thead
|
|
: sleeps 'no_event_wait' mili-seconds).
|
|
: 'loop_max == 800' and 'no_event_tick == 10' are defalut.
|
|
: 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 warinig message but ignore the exception.
|
|
: If nil, no warning message and ignore the excepsion.
|
|
: 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 falsr 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 extention 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 regist 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 operateion for the current bindtag and
|
|
: starts the operation for the next buindtag 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)
|