summaryrefslogtreecommitdiff
path: root/ext/tk/MANUAL_tcltklib.eng
blob: 9e7bd20d375006d1006331762defb7e90e5cf202 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
(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. 

    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)