summaryrefslogtreecommitdiff
path: root/ext/tk/MANUAL_tcltklib.eng
diff options
context:
space:
mode:
Diffstat (limited to 'ext/tk/MANUAL_tcltklib.eng')
-rw-r--r--ext/tk/MANUAL_tcltklib.eng445
1 files changed, 0 insertions, 445 deletions
diff --git a/ext/tk/MANUAL_tcltklib.eng b/ext/tk/MANUAL_tcltklib.eng
deleted file mode 100644
index 1db61f2..0000000
--- a/ext/tk/MANUAL_tcltklib.eng
+++ /dev/null
@@ -1,445 +0,0 @@
-(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 methods]
- 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.
-
- _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.
-
-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).
-
-(eof)