From b860656cb01b05ac26cd0a11d6c79c3875b78ebe Mon Sep 17 00:00:00 2001 From: nagai Date: Fri, 17 Oct 2003 07:59:32 +0000 Subject: add some documents git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@4793 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ext/tcltklib/MANIFEST | 2 + ext/tcltklib/MANUAL.eng | 264 ++++++++++++++++++++++++++++++++++++++++++++++++ ext/tcltklib/MANUAL.euc | 7 +- ext/tcltklib/README.1st | 33 ++++++ ext/tk/MANIFEST | 1 + ext/tk/README.1st | 21 ++++ ext/tk/lib/tk.rb | 3 + 7 files changed, 328 insertions(+), 3 deletions(-) create mode 100644 ext/tcltklib/MANUAL.eng create mode 100644 ext/tcltklib/README.1st create mode 100644 ext/tk/README.1st (limited to 'ext') diff --git a/ext/tcltklib/MANIFEST b/ext/tcltklib/MANIFEST index 7337bbeba5..e06547a6aa 100644 --- a/ext/tcltklib/MANIFEST +++ b/ext/tcltklib/MANIFEST @@ -1,6 +1,8 @@ MANIFEST +README.1st README.euc MANUAL.euc +MANUAL.eng tcltklib.c stubs.c depend diff --git a/ext/tcltklib/MANUAL.eng b/ext/tcltklib/MANUAL.eng new file mode 100644 index 0000000000..a037d18d41 --- /dev/null +++ b/ext/tcltklib/MANUAL.eng @@ -0,0 +1,264 @@ +(tof) + 2003/10/17 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 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_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. + + +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. + + 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. + + 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) + _fromUTF8(str, encoding) + : 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. + + 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) diff --git a/ext/tcltklib/MANUAL.euc b/ext/tcltklib/MANUAL.euc index 90b32f00c7..9f9c77da02 100644 --- a/ext/tcltklib/MANUAL.euc +++ b/ext/tcltklib/MANUAL.euc @@ -1,5 +1,5 @@ (tof) - 2003/10/12 Hidetoshi NAGAI + 2003/10/17 Hidetoshi NAGAI 本ドキュメントには古い tcltk ライブラリ，tcltklib ライブラリの説明 が含まれていますが，その記述内容は古いものとなっています． @@ -151,7 +151,8 @@ require "tcltklib" : 指定 ) を定数として定義したモジュール．以下の定数が含まれる． 定数 NONE - : いかなる種類のイベントも処理対象としない ( == 0 ) + : 値は 0 で，値としてはいかなる種類のイベントも指定していない + : ことになるが，実際の処理上は ALL と同じとして扱われる． 定数 WINDOW : window イベントを処理対象とする @@ -212,7 +213,7 @@ require "tcltklib" : チングだけが行われる ( see set_eventloop_weight )． : ただし，稼働しているスレッドがイベントループだけの場合， : timer_tick を 0 に設定することはできない．もし設定されて - : いたら，200 ms ( see NO_THREAD_INTERRUPT_TIME ) に自動設 + : いたら，100 ms ( see NO_THREAD_INTERRUPT_TIME ) に自動設 : 定される． : 詳細な説明は略すが，これは CPU パワーを節約しつつ安全で : 安定した動作を実現するために実装した仕様である． diff --git a/ext/tcltklib/README.1st b/ext/tcltklib/README.1st new file mode 100644 index 0000000000..14c56fd410 --- /dev/null +++ b/ext/tcltklib/README.1st @@ -0,0 +1,33 @@ +To compile 'tcltklib', you must have Tcl/Tk libraries on your environment. +Although 'extconf.rb' script searches Tcl/Tk libraries and header files, +sometimes fails to find them. And then, 'tcltklib' cannot be compiled. If +Tcl/Tk libraries or header files are installed but are not found, you can +give the information by arguments of the 'configure' script. Please give +some or all of the following options. + + --with-tcllib= (e.g. libtcl8.3.so ==> --with-tcllib=tcl8.3) + --with-tklib= (e.g. libtk8.3.so ==> --with-tklib=tk8.3) + + --enable_tcltk_stubs (if you force to enable stubs) + + --with-tcl-dir= + equal to "--with-tcl-include=/include --with-tcl-lib=/lib" + + --with-tk-dir= + equal to "--with-tk-include=/include --with-tk-lib=/lib" + + --with-tcl-include= the directry containts 'tcl.h' + --with-tk-include= the directry containts 'tk.h' + + --with-tcl-lib= the directry containts 'libtcl.so' + --with-tk-lib= the directry containts 'libtk.so' + +If you forgot to give the options when do 'configure' on toplevel +directry of Ruby sources, please try something like as the followings. + + $ cd ext/tcltklib + $ rm Makefile + $ CONFIGURE_ARGS='--with-tcl-include=/usr/local/include/tcl8.3/ --with-tcllib=tcl8.3 --with-tklib=tk8.3 --enable-tcltk_stubs' ruby extconf.rb + +========================================================== + Hidetoshi NAGAI (nagai@ai.kyutech.ac.jp) diff --git a/ext/tk/MANIFEST b/ext/tk/MANIFEST index 7b7b7d846f..1f46c670ec 100644 --- a/ext/tk/MANIFEST +++ b/ext/tk/MANIFEST @@ -1,4 +1,5 @@ MANIFEST +README.1st extconf.rb depend tkutil.c diff --git a/ext/tk/README.1st b/ext/tk/README.1st new file mode 100644 index 0000000000..ff92fdd8a3 --- /dev/null +++ b/ext/tk/README.1st @@ -0,0 +1,21 @@ +If you want to use Ruby/Tk (tk.rb and so on), you must have +tcltklib.so which is working collectry. If you fail to call +'require "tcltklib"', you may not have tcltklib.so. +Even if there is a tcltklib.so on your Ruby library directry, +it will not work without Tcl/Tk libraries (e.g. libtcl8.4.so) +on your environment. You must also check that your Tcl/Tk is +installed properly. + +-------------------------------------------- + ( the following is written in EUC-JP ) + +Ruby/Tk (tk.rb など) を使いたい場合には，tcltklib.so が正しく +動いていなければなりません．もし require "tcltklib" に失敗する +ようなら，tcltklib.so が存在していないのかもしれません． +たとえ Ruby のライブラリディレクトリに tcltklib.so が存在して +いたとしても，実行環境に Tcl/Tk ライブラリ (libtcl8.4.so など) +がなければ機能しません．Tcl/Tk が正しくインストールされているか +どうかもチェックしてください． + +========================================================== + Hidetoshi NAGAI (nagai@ai.kyutech.ac.jp) diff --git a/ext/tk/lib/tk.rb b/ext/tk/lib/tk.rb index 4cb11363e1..e79d97ac8e 100644 --- a/ext/tk/lib/tk.rb +++ b/ext/tk/lib/tk.rb @@ -1577,6 +1577,9 @@ module Tk def self.new(str) super(str, 'utf-8') end + def self.new_without_escape(str) + super(str, 'utf-8') + end end def Tk.UTF8_String(str) Tk::UTF8_String.new(str) -- cgit v1.2.3