Module rstk::wish

Core functions and data structures for interacting with the wish process.

The basic structure of a program using wish is as follows:

fn main() {
  let root = rstk::start_wish().unwrap();

  // -- add code here to create program

  rstk::mainloop();
}

The call to start_wish starts the “wish” program and sets up some internal structure to store information about your program’s interaction with wish. The return value is a Result, so must be unwrapped (or otherwise handled) to obtain the top-level window.

If you are using a different program to “wish”, e.g. a tclkit, then call instead:

  let root = rstk::start_with("tclkit").unwrap();

All construction of the GUI must be done after starting a wish process.

(For debugging purposes, trace_with additionally displays all messages to/from the wish program on stdout.)

Tk is event-driven, so the code sets up the content and design of various widgets and associates commands to particular events: events can be button-clicks or the movement of a mouse onto a canvas.

Once the GUI is created, then the mainloop must be started, which will process and react to events: the call to mainloop is usually the last statement in the program.

The program will usually exit when the top-level window is closed. However, that can be over-ridden or, to exit in another way, use end_wish.

Low-level API

The modules in this crate aim to provide a rust-friendly, type-checked set of structs and methods for using the Tk library.

However, there are many features in Tk and not all of them are likely to be wrapped. If there is a feature missing they may be used by directly calling Tk commands through the low-level API.

1. every widget has an id field, which gives the Tk identifier.
2. tell_wish sends a given string directly to wish
3. ask_wish sends a given string directly to wish and returns, as a String, the response.

For example, label’s takefocus flag is not wrapped. You can nevertheless set its value using:

let label = rstk::make_label(&root);

rstk::tell_wish(&format!("{} configure -takefocus 0", &label.id));

Also useful are:

• cget - queries any option and returns its current value
• configure - used to set any option to a value
• winfo - returns window-related information

Extensions

Extensions can be created with the help of next_wid, which returns a new, unique ID in Tk format. Writing an extension requires:

1. importing the tcl/tk library (using tell_wish)
2. creating an instance of the underlying Tk widget using a unique id
3. retaining that id in a struct, for later reference
4. wrapping the widget’s functions as methods, calling out to Tk with the stored id as a reference.

Structs

• TkError
  Reports an error in interacting with the Tk program.

Functions

• ask_wish
  Sends a message (tcl command) to wish and expects a result. Returns a result as a string
• end_wish
  Used to cleanly end the wish process and current rust program.
• mainloop
  Loops while GUI events occur
• next_var
  Returns a new variable name. This is used in the chart module to reference the chart instances in Tk.
• next_wid
  Returns a new id string which can be used to name a new widget instance. The new id will be in reference to the parent, as is usual in Tk.
• start_wish
  Creates a connection with the “wish” program.
• start_with
  Creates a connection with the given wish/tclkit program.
• tell_wish
  Sends a message (tcl command) to wish.
• trace_with
  Creates a connection with the given wish/tclkit program with debugging output enabled (wish interactions are reported to stdout).