Public API

TclObj(val) -> obj

Return a Tcl object storing value val. The initial type of the Tcl object, given by obj.type, depends on the type of val:

• A string, symbol, or character is stored as a Tcl :string.

• A Boolean or integer is stored as a Tcl :int or :wideInt.

• A non-integer real is stored as a Tcl :double.

• A dense vector of bytes (UInt8) is stored as a Tcl :bytearray.

• A tuple is stored as a Tcl :list.

• A Tcl object is returned unchanged. Call copy to have an independent copy.

If the content of a Tcl object is valid as a list, the object may be indexed, elements may be added, deleted, etc.

Properties

Tcl objects have the following properties:

• obj.refcnt yields the reference count of obj. If obj.refcnt > 1, the object is shared and must be copied before being modified.

• obj.ptr yields the pointer to the Tcl object, this is the same as pointer(obj).

• obj.type yields the current internal type of obj as a symbol. This type may change depending on how the object is used by Tcl. For example, after having evaluated a script in a Tcl string object, the object internal state becomes :bytecode to reflect that it now stores compiled byte code.

Conversion

Call convert(T, obj) to get a value of type T from Tcl object obj. The content of a Tcl object may always be converted into a string by calling convert(String, obj), string(obj), or String(obj) which all yield a copy of this string.

See also

TclTk.list or TclTk.concat for building Tcl objects to efficiently store arguments of Tcl commands.

Methods TclTk.Impl.value_type and TclTk.Impl.new_object may be extended to convert other types of value to Tcl object.

TclTk.concat(args...) -> lst
interp.concat(args...) -> lst

Build a list of Tcl objects obtained by concatenating the elements of the arguments arg... each being considered as a list. This mimics the behavior of the Tcl concat command.

In the second above example, interp is a Tcl interpreter used to retrieve a more informative error message in case of error.

See also

TclTk.list, TclTk.eval, TclObj, and TclInterp.

 TclTk.list(args...) -> lst
 interp.list(args...) -> lst

Build a list lst of Tcl objects such that each of args... is a single element of lst. This mimics the behavior of the Tcl list command.

In the second above example, interp is a Tcl interpreter used to retrieve an error message in case of failure.

See also

TclTk.concat, TclTk.eval, TclObj, and TclInterp.

interp = TclInterp()
interp = TclInterp(:shared | :private)

Return a Tcl interpreter. If argument is :shared or unspecified, an interpreter shared by all tasks running on the current thread is returned. If argument is :private, a new private interpreter is created.

The resulting object can be used as a function to execute a Tcl command. For example:

julia> interp(:set, :x, 42)
TclObj(42)

The result of the command is returned as a Tcl object storing the value 42. See TclTk.exec for more details about execution of Tcl commands.

To evaluate a Tcl script with the interpreter, call interp.eval(args...). The above example can also be done by:

julia> interp.eval("set x 42")
TclObj("42")

whose result is a Tcl object storing the string "42". See method TclTk.eval for more details about script evaluation.

The interp object can also be indexed as an array to access global Tcl variables (the variable name can be specified as a string or as a symbol):

interp["x"]          # yields value of variable "x"
interp[:tcl_version] # yields version of Tcl
interp[:x] = 33      # set the value of "x" and yields its value

The Tcl interpreter is initialized and will be deleted when no longer in use. If Tk has been properly installed, then:

interp.eval("package require Tk")

should load Tk extension and create the "." toplevel Tk window. But see tk_start method to load Tk.

TclTk.eval(T=TclObj, interp=TclInterp(), args...) -> res::T
interp.eval(T=TclObj, args...) -> res::T

Concatenate arguments args... into a list, evaluate this list as a Tcl script with interpreter interp, and return a value of type T.Any key => val pair in args... is converted in the pair of arguments -key and val in the script list (note the hyphen before the key name).

The evaluation of a Tcl script stores a result (or an error message) in the interpreter and returns a status. The behavior of TclTk.eval depend on the type T of the expected result:

• If T is TclStatus, the status of the evaluation is returned and the script result may be retrieved by calling TclTk.getresult or via interp.result(...).

• If T is Nothing, an exception is thrown if the status is not TCL_OK and nothing is returned otherwise (i.e., the result of the script is ignored).

• Otherwise, an exception is thrown if the status is not TCL_OK and the result of the script is returned as a value of type T otherwise.

See also

See TclTk.concat for the rules to concatenate arguments into a list (apart from the accounting of pairs).

See TclTk.exec for another way to execute a Tcl command where each of args... is considered as a distinct command argument.

TclTk.exec(T=TclObj, interp=TclInterp(), args...) -> res::T
interp.exec(T=TclObj, args...) -> res::T
interp(T=TclObj, args...) -> res::T

Make a list out of the arguments args..., evaluate this list as a Tcl command with interpreter interp, and return a value of type T. Any key => val pair in args... is converted in the pair of arguments -key and val in the command list (note the hyphen before the key name).

The evaluation of a Tcl command stores a result (or an error message) in the interpreter and returns a status. The behavior of TclTk.exec depends on the type T of the expected result:

• If T is TclStatus, the status of the evaluation is returned and the command result may be retrieved by calling TclTk.getresult or via interp.result(...).

• If T is Nothing, an exception is thrown if the status is not TCL_OK and nothing is returned otherwise (i.e., the result of the command is ignored).

• Otherwise, an exception is thrown if the status is not TCL_OK and the result of the command is returned as a value of type T otherwise.

See also

See TclTk.list for the rules to build a list (apart from the accounting of pairs).

See TclTk.eval for another way to evaluate a Tcl script. The difference with TclTk.eval is that each input argument is interpreted as a different token of the Tcl command.

interp[] -> obj::TclObj
interp.result() -> obj::TclObj
TclTk.getresult() -> obj::TclObj
TclTk.getresult(interp) -> obj::TclObj

interp.result(T) -> val::T
TclTk.getresult(T) -> val::T
TclTk.getresult(T, interp) -> val::T
TclTk.getresult(interp, T) -> val::T

Retrieve the result of interpreter interp as a value of type T or as a Tacl object if T is not specified. TclTk.getresult returns the result of the shared interpreter of the thread.

See also

TclInterp and TclObj.

TclTk.setresult!(interp = TclInterp(), val) -> nothing

Set the result stored in Tcl interpreter interp with val.

If not specified, interp is the shared interpreter of the calling thread.

TclTk.quote_string(str)

Return string str a valid Tcl string surrounded by double quotes that can be directly inserted in Tcl scripts.

This is similar to escape_string but specialized to represent a valid Tcl string surrounded by double quotes in a script.

TclStatus

Type of result returned by evaluating Tcl scripts or commands. Possible values are:

• TCL_OK: Command completed normally; the interpreter's result contains the command's result.

• TCL_ERROR: The command couldn't be completed successfully; the interpreter's result describes what went wrong.

• TCL_RETURN: The command requests that the current function return; the interpreter's result contains the function's return value.

• TCL_BREAK: The command requests that the innermost loop be exited; the interpreter's result is meaningless.

• TCL_CONTINUE: Go on to the next iteration of the current loop; the interpreter's result is meaningless.

TclError(args...)
TclError(interp::TclInterp)

Return a TclError exception with error message given by string(args...) or taken from the last result in interpreter interp.

tcl_error(args...)
tcl_error(interp::TclInterp)

Throw a TclError exception with error message given by string(args...) or taken from the last result in interpreter interp.

TclTk.exists(interp=TclInterp(), name)
haskey(interp, name)

Return whether global variable name is defined in Tcl interpreter interp or in the shared interpreter of the calling thread if this argument is omitted. name may be a 2-tuple (part1, part2).

See also

TclTk.getvar, TclTk.setvar!, and TclTk.unsetvar!.

TclTk.getvar(T=TclObj, interp=TclInterp(), name) -> val::T
interp[name] -> val::TclObj
interp[T::Type, name] -> val::T

Return the value of the global variable name in Tcl interpreter interp or in the shared interpreter of the calling thread if this argument is omitted. name may be a 2-tuple (part1, part2).

Optional argument T (TclObj by default) can be used to specify the type of the returned value. Some possibilities are:

• If T is TclObj (the default), a managed Tcl object is returned. This is the most efficient if the returned value is intended to be used in a Tcl list or as an argument of a Tcl script or command.

• If T is Bool, a boolean value is returned.

• If T is String, a string is returned.

• If T is Char, a single character is returned (an exception is thrown if Tcl object is not a single character string).

• If T <: Integer, an integer value of type T is returned.

• If T <: AbstractFloat, a floating-point value of type T is returned.

Note that, except if T is TclObj, a conversion of the Tcl object stored by the variable may be needed.

See also

TclTk.exists, TclTk.setvar!, and TclTk.unsetvar!.

TclTk.setvar!(interp=TclInterp(), name, value) -> nothing
interp[name] = value

TclTk.setvar!(T, interp=TclInterp(), name, value) -> val::T

Set global variable name or part1(part2) to be value in Tcl interpreter interp or in the shared interpreter of the calling thread if this argument is omitted. name may be a 2-tuple (part1, part2).

The Tcl variable is deleted if value is unset, the singleton provided by the UnsetIndex package and exported by the Tcl package.

In the last case, the new value of the variable is returned as an instance of type T (can be TclObj). The new value may be different from value because of trace(s) associated to this variable.

See also

TclTk.getvar, TclTk.exists, and TclTk.unsetvar!.

TclTk.unsetvar!(interp=TclInterp(), name)
interp[name] = unset
delete!(interp, name) -> interp

Delete global variable name in Tcl interpreter interp or in the shared interpreter of the thread if this argument is omitted. name may be a 2-tuple (part1, part2). Above, unset is the singleton provided by the UnsetIndex package and exported by the TclTk package.

Keywords

Keyword nocomplain can be set true to ignore errors. By default, nocomplain=false.

Keyword flag can be set with bits such as TCL_GLOBAL_ONLY (set by default) and TCL_LEAVE_ERR_MSG (set by default unless nocomplain is true).

See also

TclTk.getvar, TclTk.exists, and TclTk.setvar!.

tk_start(interp = TclInterp()) -> interp

Load Tk and Ttk packages in interp and start the event loop (for all interpreters).

See also

TclTk.resume, TclInterp, and TkWidget.

TclTk.do_events(flags = TCL_DONT_WAIT|TCL_ALL_EVENTS) -> num::Int

Process Tcl/Tk events for all interpreters by calling TclTk.do_one_event(flags) until there are no events matching flags and return the number of processed events. Normally this is automatically called by the timer set by TclTk.resume.

TclTk.do_one_event(flags = TCL_DONT_WAIT|TCL_ALL_EVENTS) -> bool

Process at most one Tcl/Tk event for all interpreters matching flags and return whether one such event was processed. This function is called by TclTk.do_events.

TclTk.resume(delay=0.1, interval=0.05) -> nothing

Resume or start the processing of Tcl/Tk events with a given delay and interval both in seconds. This manages to repeatedly call function TclTk.do_events. The method TclTk.suspend can be called to suspend the processing of events.

Calling TclTk.resume is mandatory when Tk extension is loaded. Thus, the recommended way to load the Tk package is:

TclTk.eval(interp, "package require Tk")
TclTk.resume()

or alternatively:

tk_start()

can be called to do that.

TclTk.suspend() -> nothing

Suspend the processing of Tcl/Tk events for all interpreters. The method TclTk.resume can be called to resume the processing of events.

TkWidget(interp=TclInterp(), path)

Return a widget for the given Tk window path in interpreter interp. The type of the widget is inferred from the class of the Tk window.

TclTk.grid(args...)

Call Tk grid geometry manager. One of the arguments must be a widget (that is an instance of TkWidget). All widgets in args... must live in the same interpreter.

See also

TclTk.pack and TclTk.place.

TclTk.pack(args...)

Call Tk packer geometry manager. One of the arguments must be a widget (that is an instance of TkWidget). All widgets in args... must live in the same interpreter.

For example:

using TclTk
tk_start()
top = TkToplevel()
TclTk.exec(Nothing, :wm, :title, top, "A simple example")
btn = TkButton(top, :text => "Click me", :command => "puts {ouch!}")
TclTk.pack(Nothing, btn, :side => :bottom, :padx => 30, :pady => 5)

See also

TclTk.grid and TclTk.place.

TclTk.place(args...)

Call Tk placer geometry manager. One of the arguments must be a widget (that is an instance of TkWidget). All widgets in args... must live in the same interpreter.

See also

TclTk.grid and TclTk.pack.