Macro tcl::tclosure

tclosure!() { /* proc-macro */ }

Helps to register rust closures as Tcl commands or Tk event callbacks.

Syntax

tclosure!( interp, cmd, args, bind, closure )

or more precisely:

tclosure!( $interp:expr, cmd:$cmd:expr, args:$args:expr, bind:($($bind: bind_syn::Bind),*), $closure:expr )

Input parameters

1. interp, the Tcl interpreter instance.

2. cmd, the name of the command being registered in Tcl. Optional. Note: be careful to keep multple closures from sharing the same cmd name.

3. args, the arguments provided in Tcl on executing the command. Optional. You can provide args if you don’t want this macro to interpret evt_*/vldt_* arguments as Tk event callback arguments.

4. bind list, for cloning data into the closure, which is similar inside bind::bind!(). Optional.

5. closure, the closure defined in Rust. Its capture must be move and move keywords could be omitted. Note: an attribute #[default(value)] on a parameter will assign a default value for this parameter.

Without args given, some special arguments starting with evt_ or vldt_ will be treated as predefined Tk event callback arguments. The annotated types can be omitted or substituted by different types.

Tk Event details

• evt_serial: c_int

The number of the last client request processed by the server (the serial field from the event). Valid for all event types.

• evt_above: c_int

The above field from the event, formatted as a hexadecimal number. Valid only for Configure events. Indicates the sibling window immediately below the receiving window in the stacking order, or 0 if the receiving window is at the bottom.

• evt_button: tk::event::ButtonNo

The number of the button that was pressed or released. Valid only for ButtonPress and ButtonRelease events.

• evt_count: c_int

The count field from the event. Valid only for Expose events. Indicates that there are count pending Expose events which have not yet been delivered to the window.

• evt_detail: Obj

The detail or user_data field from the event.

• evt_focus: bool

The focus field from the event (false or true). Valid only for Enter and Leave events, true if the receiving window is the focus window or a descendant of the focus window, false otherwise.

• evt_height: c_int

The height field from the event. Valid for the Configure, ConfigureRequest, Create, ResizeRequest, and Expose events. Indicates the new or requested height of the window.

• evt_window: c_int

The window field from the event, represented as a hexadecimal integer. Valid for all event types.

• evt_keycode: c_int

The keycode field from the event. Valid only for KeyPress and KeyRelease events.

• evt_mode: tk::event::TkNotifyMode

The mode field from the event. Valid only for Enter, FocusIn, FocusOut, and Leave events.

• evt_override: bool

The override_redirect field from the event. Valid only for Map, Reparent, and Configure events.

• evt_place: tk::event::TkPlaceOn

The place field from the event, substituted as one of the strings PlaceOnTop or PlaceOnBottom. Valid only for Circulate and CirculateRequest events.

• evt_state: String

The state field from the event. For ButtonPress, ButtonRelease, Enter, KeyPress, KeyRelease, Leave, and Motion events, a decimal string is substituted. For Visibility, one of the strings VisibilityUnobscured, VisibilityPartiallyObscured, and VisibilityFullyObscured is substituted. For Property events, substituted with either the string NewValue (indicating that the property has been created or modified) or Delete (indicating that the property has been removed).

• evt_time: c_int

The time field from the event. This is the X server timestamp (typically the time since the last server reset) in milliseconds, when the event occurred. Valid for most events.

• evt_width: c_int

The width field from the event. Indicates the new or requested width of the window. Valid only for Configure, ConfigureRequest, Create, ResizeRequest, and Expose events.

• evt_x: c_int, evt_y: c_int

The x and y fields from the event. For ButtonPress, ButtonRelease, Motion, KeyPress, KeyRelease, and MouseWheel events, evt_x and evt_y indicate the position of the mouse pointer relative to the receiving window. For key events on the Macintosh these are the coordinates of the mouse at the moment when an X11 KeyEvent is sent to Tk, which could be slightly later than the time of the physical press or release. For Enter and Leave events, the position where the mouse pointer crossed the window, relative to the receiving window. For Configure and Create requests, the x and y coordinates of the window relative to its parent window.

• evt_unicode: char

Substitutes the UNICODE character corresponding to the event, or the empty string if the event does not correspond to a UNICODE character (e.g. the shift key was pressed). On X11, XmbLookupString (or XLookupString when input method support is turned off) does all the work of translating from the event to a UNICODE character. On X11, valid only for KeyPress event. On Windows and macOS/aqua, valid only for KeyPress and KeyRelease events.

• evt_borderwidth: c_int

The border_width field from the event. Valid only for Configure, ConfigureRequest, and Create events.

• evt_delta: c_int

This reports the delta value of a MouseWheel event. The delta value represents the rotation units the mouse wheel has been moved. The sign of the value represents the direction the mouse wheel was scrolled.

• evt_sendevent: bool

The send_event field from the event. Valid for all event types, false indicates that this is a “normal” event, true indicates that it is a “synthetic” event generated by SendEvent.

• evt_keysym: char

The keysym corresponding to the event, as a textual char. Valid only for KeyPress and KeyRelease events.

• evt_matches: c_int

The number of script-based binding patterns matched so far for the event. Valid for all event types.

• evt_keysym_decimal: c_int

The keysym corresponding to the event, substituted as a number. Valid only for KeyPress and KeyRelease events.

• evt_property: String

The name of the property being updated or deleted (which may be converted to an XAtom using winfo atom.) Valid only for Property events.

• evt_root: c_int

The root window identifier from the event. Valid only for events containing a root field.

• evt_subwindow: c_int

The subwindow window identifier from the event, formatted as a hexadecimal number. Valid only for events containing a subwindow field.

• evt_type: tk::event::TkEventType

The type field from the event. Valid for all event types.

• evt_window_path: String

The path name of the window to which the event was reported (the window field from the event). Valid for all event types.

• evt_rootx: c_int, evt_rooty: c_int

The x_root and y_root fields from the event. If a virtual-root window manager is being used then the substituted values are the corresponding x-coordinate and y-coordinate in the virtual root. Valid only for ButtonPress, ButtonRelease, Enter, KeyPress, KeyRelease, Leave and Motion events. Same meaning as evt_x and evt_y, except relative to the (virtual) root window.

Validation details

• vldt_action: tk::event::TkValidatingAction

Type of action.

• vldt_index: c_int

Index of char string to be inserted/deleted, if any, otherwise -1.

• vldt_new: String

The value of the entry if the edit is allowed. If you are configuring the entry widget to have a new textvariable, this will be the value of that textvariable.

• vldt_old: String

The current value of entry prior to editing.

• vldt_text: String

The text string being inserted/deleted.

• vldt_set: tk::event::TkValidationSet

The type of validation currently set.

• vldt_op: tk::event::TkValidationOp

The type of validation that triggered the callback (key, focusin, focusout, forced).

• vldt_name: String

The name of the entry widget.

Output

Returns a String of the command name.

Example, Tk Event callback

widget.bind( button_press_2(),
    tclosure!( tk, |evt_x, evt_y| tk.popup( menu, evt_x, evt_y, None ))
)?;

Example, Poll

tk.run( tclosure!( tk, cmd:"poll" || {
    {/* poll and do lots of work, omitted */}
    tk.after( 100, ("poll",) )?;
    Ok(())
}))?;