Labs/Bespin/DeveloperGuide/Tabs

Background

When writing code for Bespin that deals in any way with cursor placement (including inserting, selecting, editing, and deleting text), it it important to keep in mind that not every character will have a one-character length—some characters have a variable length. When these characters (e.g. tabs) are on a line, there will not be a one-to-one relationship between the character position (pos) and the model position (modelPos).

As it stands now, the model stores the characters of a line in an array, with one character per array element. As far as the model is concerned, all characters are treated equally—their width is unimportant. However, the cursor engine needs to know where to put the cursor, so it needs to know how long each character is when displayed in the editor.

List of functions that require modelPos instead of pos

These functions in the model must be passed modelPos in order for the text to be manipulated properly:

• insertCharacters()
• deleteCharacters()
• splitRow()
• getChunk()
• insertChunk()
• deleteChunk()

Note: This may not be a definitive list.

How to properly deal with tabs

Don't panic! There are functions available that will help convert back and forth between pos and modelPos. These functions will greatly simplify the process of dealing with text that contains tabs (or other, unforeseen variable-length characters).

The cursor code has a number of helpful functions for this purpose, and the editor code even has counterpart helper functions to invoke some of them more easily.

getCursorPosition()

This function does exactly what it used to do: return the current cursor position. However, its functionality has now been increased to be able to convert a given modelPos into a cursor position—even if it's not the current position!

The helper function in editor is named getCursorPos().

getModelPosition()

This is a brand new function that converts a given cursor position (pos) into its proper position in the model array. If no cursor position is fed to the function, it will default to converting the current cursor position.

The helper function in editor is named getModelPos().

getCharacterLength()

This function will determine the length of the given character when present at the given cursor position column. If a column is not given, it will default to the current column. At the moment, if any character besides a tab is passed to this function, it will automatically return a length of 1. It does not accept multiple characters.

getStringLength()

This function builds upon getCharacterLength() by providing you with the length of an entire string (str), rather than just a single character.