Module _M.textui.buffer

The buffer class wraps a Textadept buffer, and extends it with support for custom styling, buffer specific key bindings and hotspot support.

It takes care of the details needed for making a text based interface work, such as mapping Textadept events to the correct buffers, working with the _M.textui.style module to ensure that styling works, etc.

How it works

When you work with a TextUI buffer, it will nearly always seem just like an ordinary Textadept buffer (but with benefits, such as support for custom styling and easy callbacks, etc.). But where an Textadept buffer is volatile, and might cease to exists at any time (due to it being closed by a user for example) a TextUI buffer is persistent.

When we say that a TextUI buffer "wraps" an Textadept buffer, there's more to it than just adding additional methods to the Textadept buffer class. A TextUI buffer will always exist, but the corresponding Textadept buffer, named target hereafter, may not. When the target buffer exists, a TextUI buffer will expose all the functions and attributes of the Textadept buffer, making it possible to use the TextUI buffer in just the same way as you would a Textadept buffer (i.e. invoking any of the ordinary buffer methods, setting attributes, etc.). The TextUI buffer takes care of creating the target buffer automatically if needed whenever you invoke buffer:show. When the target buffer does not exist, for instance as the result of the user closing it, any attempt to invoke any of the ordinary buffer methods will raise an error. You can check explicitly whether the target exists by using the buffer:is_attached function. This is not however something you will have to worry much about in practice, since you'll typically interact with the buffer as part of a refresh, key press, etc., where the target buffer will always exist.

In short, you don't have to worry about creating buffers, detecting whether the buffer was closed, etc., as long as you remember to invoke buffer:show and perform your work within the callbacks.

How to use

You create a new TextUI buffer by calling new, passing the buffer title. You specify an on_refresh handler for the buffer, which is responsible for actually inserting the content in the buffer, along with any custom styles and hotspot handlers. You specify any custom key bindings using either keys or on_keypress, and/or hook any other handlers of interest. In the on_refresh handler, you add the actual text using any of the extended text insertion functions (buffer:add_text, buffer:append_text, buffer:insert_text or possibly buffer:newline). You invoke buffer:show to show the buffer, and respond to any interactions using the provided callbacks.

Please see the examples for more hands on instructions.

Functions

new (title) Creates and returns a new textui buffer.
buffer:show () Shows the buffer.
buffer:close () Closes the buffer.
buffer:update (callback) Performs an update of the buffer contents.
buffer:refresh () Refreshes the buffer.
buffer:set_title () Updates the title of the buffer.
buffer:is_attached () Checks whether a target buffer currently exists.
buffer:is_showing () Checks whether the buffer is currently showing in any view.
buffer:is_active () Checks whether the buffer is currently active, i.e.
buffer:add_hotspot (start_pos, end_pos, command) Adds a hotspot for the given text range.
buffer:add_text (text, style, command, indicator) Override for buffer:add_text which accepts optional style, command and indicator parameters.
buffer:append_text (text, style, command, indicator) Override for buffer:append_text which accepts optional style, command and indicator parameters.
buffer:insert_text (pos, text, style, command, indicator) Override for buffer:insert_text which accepts optional style, command and indicator parameters.
buffer:newline () Override for buffer:new_line.

Fields

read_only Whether the buffer should be marked as read only.

Instance fields

on_deleted Callback invoked whenever the target buffer is deleted.
on_refresh Callback invoked whenever the buffer should refresh.
on_keypress Callback invoked whenever the buffer receives a keypress.
keys A table of key commands for the buffer.
data A general purpose table that can be used for storing state associated with the buffer.
target The target buffer, if any.


Functions

new (title)
Creates and returns a new textui buffer. The buffer will not be attached upon the return.

Parameters:

  • title: The title of the buffer. This will be displayed as the buffer's title in the Textadept top bar.
buffer:show ()
Shows the buffer. If the target buffer doesn't exist, due to it either not having been created yet or it having been deleted, it is automatically created. Upon the return, the buffer is showing and set as the global buffer.
buffer:close ()
Closes the buffer.
buffer:update (callback)
Performs an update of the buffer contents. You invoke this with a callback that will do the actual update. This function takes care of ensuring that the target is writable, and handles setting the save point, etc.

Parameters:

  • callback: The callback to invoke to perform the update. The callback will receive the buffer instance as its sole parameter.
buffer:refresh ()
Refreshes the buffer. A refresh works by ensuring that it's possible to write to the buffer and invoking the on_refresh handler. After the refresh is complete, the read_only state is reset to whatever it was before the refresh, and a save point is set.

Please note that a refresh will clear all content, along with hotspots, etc. If you want to perform smaller updates please use the buffer:update function instead.

buffer:set_title ()
Updates the title of the buffer.
buffer:is_attached ()
Checks whether a target buffer currently exists.

Returns:

    true if the target buffer exists and false otherwise
buffer:is_showing ()
Checks whether the buffer is currently showing in any view.

Returns:

    true if the buffer is showing and false otherwise
buffer:is_active ()
Checks whether the buffer is currently active, i.e. the current buffer.

Returns:

    true if the buffer is active and false otherwise
buffer:add_hotspot (start_pos, end_pos, command)
Adds a hotspot for the given text range. Hotspots allows you to specify the behaviour for when the user selects certain text. Besides using this function directly, it's also possible and in many cases more convinient to add an hotspot when using any of the text insertion functions (buffer:add_text, buffer:append_text, buffer:insert_text). Note that the range given is interpreted as being half closed, i.e. [start_pos, end_pos).

NB: Please note that all hotspots are cleared as part of a refresh.

Parameters:

  • start_pos: The start position
  • end_pos: The end position. The end position itself is not part of the hotspot.
  • command:

    The command to execute. Similarily to keys, command can be either a function or a table. When the command is a function, it will be passed the following parameters:

    • buffer: The buffer instance
    • shift: True if the Shift key was held down.
    • ctrl: True if the Control/Command key was held down.
    • alt: True if the Alt/option key was held down.
    • meta: True if the Control key on Mac OSX was held down.
buffer:add_text (text, style, command, indicator)
Override for buffer:add_text which accepts optional style, command and indicator parameters.

Parameters:

  • text: The text to add.
  • style: The style to use for the text, as defined using _M.textui.style.
  • command: The command to run if the user "selects" this text. See buffer:add_hotspot for more information.
  • indicator: Optional _M.textui.indicator to use for the added text.
buffer:append_text (text, style, command, indicator)
Override for buffer:append_text which accepts optional style, command and indicator parameters.

Parameters:

  • text: The text to append.
  • style: The style to use for the text, as defined using _M.textui.style.
  • command: The command to run if the user "selects" this text. See buffer:add_hotspot for more information.
  • indicator: Optional _M.textui.indicator to use for the appended text.
buffer:insert_text (pos, text, style, command, indicator)
Override for buffer:insert_text which accepts optional style, command and indicator parameters.

Parameters:

  • pos: The position to insert text at or -1 for the current position.
  • text: The text to insert.
  • style: The style to use for the text, as defined using _M.textui.style.
  • command: The command to run if the user "selects" this text. See buffer:add_hotspot for more information.
  • indicator: Optional _M.textui.indicator to use for the inserted text.
buffer:newline ()
Override for buffer:new_line. A TextUI buffer will always have eol mode set to LF, so it's also possible, and arguably easier, to just insert a newline using the \n escape via any of the other text insertion functions.

Fields

read_only
Whether the buffer should be marked as read only. The default is true but can be changed on a buffer to buffer basis. Any call to buffer:refresh will automatically take care of setting the buffer to write mode before invoking the on_refresh handler, and will restore the read_only state afterwards.

Instance fields

These can be set only for an buffer instance, and not globally for the module.
on_deleted
Callback invoked whenever the target buffer is deleted. The callback has the following with the following parameters: buffer
on_refresh
Callback invoked whenever the buffer should refresh. This should set for each buffer. It is this callback that is responsible for actually inserting any content into the buffer. Before this callback is invoked, any previous buffer content will be cleared. The callback will be invoked with the buffer as the sole parameter.

see also:

on_keypress
Callback invoked whenever the buffer receives a keypress. Please note that if there is any key command defined in keys matching the keypress, that key command will be invoked and this callback will never be called. The callback will receive the following parameters:

  • buffer: The buffer instance.
  • key: The "translated key" (same format as for keys).
  • code: The key code.
  • shift: True if the Shift key was held down.
  • ctrl: True if the Control/Command key was held down.
  • alt: True if the Alt/option key was held down.
  • meta: True if the Control key on Mac OSX was held down.

It's similar to the standard Textadept KEYPRESS event (which you can read more about here). The return value determines whether the key press should be propagated, just the same as for the standard Textadept event.

see also:

keys
A table of key commands for the buffer. This is similar to _M.textadept.keys works, but allows you to specify key commands specifically for one buffer. The format for specifying keys is the same as for _M.textadept.keys, and the values assigned can also be either functions or tables. There are differences compared to _M.textadept.keys however:

  • It's not possible to specify language specific key bindings. This is obviously not applicable for a textui buffer.
  • It's not possible to specify keychain sequences.
  • For function values, the buffer instance is passed as the first argument.
  • For table values, buffer or view references will not be magically fixed. This means that you should not use either of the above in a table command, unless you enjoy the occasional segfault.

In short, only explicit simple mappings are supported. Defining a key command for a certain key means that key presses are never propagated any further for that particular key. Key commands take preference over any on_keypress callback, so any such callback will never be called if a key command matches.

see also:

data
A general purpose table that can be used for storing state associated with the buffer. The data table is special in the way that it will automatically be cleared whenever the user closes the buffer.
target
The target buffer, if any. This holds a reference to the target buffer, when present.
generated by LDoc 1.1