Bintracker Internal State

[module] bt-state

[variable] *bintracker-version*

default: "0.2.0"

[variable] *bintracker-state*

default: (make-app-state)

[procedure] (now)

Return the current local time as a string in the form "day_mon_dd_hh-mm-ss_yyyy"

[procedure] (state #!optional PARAM)

Get the global application state, or a specific PARAMeter of that state.

[procedure] (ui)

Accessor for the main application's GUI widget structure, which is a <ui-metabuffer> instance.

[procedure] (repl)

Accessor for the default repl buffer widget which is an instance of <ui-repl>.

[procedure] (colors . ARGS)

This is the interface to Bintracker's application colors. It is a procedure that can be called as follows:

(colors SETTING)

Returns the current value of SETTING.

(colors 'set SETTING VAL)

Sets the current value of SETTING. VAL may be a string containing an HTML RGB color code, or a valid Tk color name.

(colors 'load COLOR-SCHEME)

Loads and applies a color scheme from a configuration file in config/color-schemes. COLOR-SCHEME must a string naming the config file, without path or extension.

[procedure] (set-global! PREFIX OBJ PARAM VAL)

All-purpose shorthand setter, used to implement set-conf!, etc.

[procedure] (set-state! PARAM VAL)

Change Bintracker's internal state variables.

[procedure] (get-keybinding-group KEY-GROUP)

Return the alist of key-bindings in the given KEY-GROUP.

[procedure] (set-keybinding-group! KEY-GROUP GROUP-LST)

Set the alist of keybindings in the given KEY-GROUP to GROUP-LST.

[procedure] (bind-keys! KEY-GROUP KEY-SPEC ACTION . ARGS)

Create a new key binding, or replace an existing one. KEY-GROUP must be one of 'global, 'console, 'edit, 'note-keys, or 'plugins. KEY-SPEC shall be a key binding specifier, using Tk's angular bracket syntax. ACTION shall be the name of a procedure or quoted lambda definition, unless KEY-GROUP is note-entry. In that case, it should be a note name, optionally followed by an octave offset.

[procedure] (key-binding KEY-GROUP KEY-SPEC)

Look up a key binding in the keymap table. Returns #f if KEY-SPEC` is not bound in KEY-GROUP.

[procedure] (inverse-key-binding KEY-GROUP ACTION)

Look up the key binding for ACTION in the given KEY-GROUP.

[procedure] (key-binding->info KEY-GROUP ACTION)

Construct an info string for the key binding of the given ACTION in the given KEY-GROUP.

[procedure] (load-keymap NAME)

Load a keymap. NAME shall be the name of the keymap file to load, without extension or path. Keymaps are expected to reside in config/keymaps. Loading a keymap does not change active bindings in a running bintracker instance. You need to call update-key-bindings! for changes to take effect.

UI Focus Control

[procedure] (make-focus-control #!optional (ZONES '()) (HIDDEN '()))

Returns a UI focus controller, which is a closure that manages the user input focus of a window (ie. a Tk toplevel). A UI buffer within a window is focussed if the buffer's specific event bindings (keypresses etc.) are active. In other words, the buffer that the user currently interacts with that buffer has focus.

A focus controller holds any number of control entries in a ring. Each control entry specifies two procedures, which perform the necessary steps to focus resp. unfocus a single UI buffer.

If you are deriving classes from <ui-buffer>, you most likely want to implement focus control support. To do so, you need to do the following:

• provide a slot for a focus controller
• generate a unique focus entry ID
• provide a constructor that performs the necessary steps to add the resulting widget to the focus controller (see documentation on adding control entries below). Usually you will want to provide ui-focus and ui-unfocus methods and register them as the focus/unfocus procedures.

Bintracker uses a controller named focus to manage the main application's top-level window. See below for more information. When implementing your own top-level windows (eg. plugin dialogues) and automatic focus traversal by Tk is not sufficient, you can use a focus controller to manage input focus manually.

The optional ZONES argument may be a list of initial focus control entries. A control entry has the following structure:

(ID FOCUS-THUNK UNFOCUS-THUNK BUFFER)

where ID is a unique identifier, FOCUS-THUNK is a procedure with no arguments that will be called when the associated UI buffer takes focus, UNFOCUS-THUNK is a procedure with no arguments that will be called when the UI buffer loses focus, and BUFFER is the UI buffer element that owns the focus zone.

You can interact with the resulting focus controller FC as follows:

(FC 'add ID FOCUS-THUNK UNFOCUS-THUNK BUFFER ['after ID-AFTER])

Adds a focus control entry. ID, FOCUS-THUNK, and UNFOCUS-THUNK are as described in the previous paragraph. If after ID-AFTER is specified, then the new zone will be added after the control entry ID-AFTER in the controller ring. Adding an entry with an ID that already exists in the ring has no effect.

(FC 'remove ID)

Remove the focus control entry ID from the ring.

(FC 'next)

Pass input focus control to the next entry in the ring.

(FC 'previous)

Pass input focus control to the previous entry in the ring.

(FC 'set ID [FORCE?])

Pass input focus control to control entry ID. Hidden entries are ignored unless FORCE? is #t.

(FC 'hide ID)
(FC 'unhide ID)

Hide or unhide the given entry. A hidden entry is ignored by the next and previous actions, and set actions require the force? flag to be effective.

(FC 'visible? ID)

Returns #t if the given entry is not hidden.

(FC 'suspend)

Temporarily disable the focus controller. Unfocusses the currently active entry.

(FC 'resume)

Re-enable a suspended focus controller. Focus passes to the entry that last held control.

(FC 'which)

Returns the currently active focus control entry.

(FC 'assoc ID)

Returns the ui buffer associated with the focus entry ID.

(FC 'list)

List the current entries in the ring, with the active one as the first element.

[procedure] (focus ACTION . ARGS)

The focus controller for the main application window. See make-focus-control above for details on how to interact with focus control. Any UI buffer within Bintracker's main application window must register with this controller. This probably applies to your code, if you use <ui-buffer> and directly modify things within the main UI.

[procedure] (focus-next-ui-zone)

[procedure] (focus-previous-ui-zone)

The Journal (Edit History)

Bintracker uses a dual undo/redo stack system to track user edits.

On every edit, the redo stack is cleared, and the executed edit action is pushed to the undo stack, which is part of *bintracker-state*. See bt-gui/Editing for a description of edit actions.

On push-undo, the first element of the undo stack is popped and pushed to the redo stack.

Likewise, on push-redo, the first element of the redo stack is popped and pushed to the undo stack.

The undo stack size is limited by the journal-limit global setting.

[procedure] (make-reverse-action ACTION MMOD)

Generate an action specification that when applied, will revert the edit that results from the given edit ACTION specification.

The Clipboard

[procedure] (clipboard . ARGS)

The global application clipboard. Call this procedure with no arguments to retrieve the current contents of the clipboard. Call it as follows to copy a new chunk of data to the clipboard:

(clipboard 'put CONTENT)

Clipboard CONTENT may be any value except #f. Any component reading from the clipboard is responsible for checking if the current clipboard contents are suitable for the task at hand.

MDAL field node data is commonly stored as a plain list of values (for a single field node) or a list of such lists (for multiple field nodes).

[procedure] (copy ARG)

Error Handling

[procedure] (exn->message EXN)

Return a string representing a human-readable representation of the exception object EXN.

[procedure] (write-crash-log EXN #!key STACK-TRACE MMOD-DUMP)

Write a log file with information on the current crash. Returns the filename of the log file.