File Buffer Functions
This example enumerates all the open buffer handles: cbuf = BufListCount() ibuf = 0 while (ibuf < cbuf)
{
hbuf = BufListItem(ibuf)
// ... do something with buffer hbuf
ibuf = ibuf + 1
}
File Buffer Functions
File buffer functions are used to create and manipulate file buffers and the text within them. A file buffer is the loaded image of a text file. File buffers are edited by the user and then saved back to disk with the Save command.
Many of the file buffer functions use buffer handles (hbuf). These are handles to open file buffers. An hbuf is typically a small integer value. An hbuf value of hNil
(zero) indicates an error.
AppendBufLine (hbuf, s)
Appends a new line of text s to the file buffer hbuf.
ClearBuf (hbuf)
Empties the buffer hbuf so that it contains no lines.
CloseBuf (hbuf)
Closes a file buffer. Hbuf is the buffer handle.
CopyBufLine (hbuf, ln)
Copies the line ln from the file buffer hbuf to the clipboard.
DelBufLine (hbuf, ln)
Deletes the line ln from the file buffer hbuf.
GetBufHandle (filename)
Returns the handle of the open file buffer whose name is filename. This function searches all open file buffers to find the one that matches the given filename parameter. GetBufHandle returns hNil if no buffer can be found with the given file name.
GetBufLine (hbuf, ln)
Returns the text of the line ln in the given file buffer hbuf.
GetBufLineCount (hbuf)
Returns the number of lines of text in a file buffer. Hbuf is the file buffer handle.
GetBufLineLength (hbuf, ln)
Returns the number of characters on the line ln in the given file buffer hbuf.
388 Source Insight 4 User Guide
File Buffer Functions
GetBufLnCur (hbuf)
Returns the current line number of the user's selection inside of the file buffer hbuf. A macro error is generated if the given file buffer is not already displayed in a source file window.
GetBufName (hbuf)
Returns the name of the file associated with a file buffer. Hbuf is the file buffer handle.
GetBufProps (hbuf)
Returns a Bufprop record, which contains properties for the given buffer. See “Bufprop Record” on page 379.
GetBufSelText (hbuf)
Returns the selected characters in the file buffer hbuf as a string. A maximum of one line of text is returned.
This is useful for getting the text of a word selection. A macro error is generated if the given file buffer is not already displayed in a source file window.
GetCurrentBuf ()
Returns a handle to the current buffer. The current buffer is the file buffer that appears in the front-most source file window. Returns hNil if there is no current buffer (i.e. no open source file windows).
InsBufLine (hbuf, ln, s)
Inserts a new line of text s for line number ln in the file buffer hbuf.
IsBufDirty (hbuf)
Returns True if the buffer is dirty. A dirty buffer is one that has been edited since it was opened or saved. A dirty buffer contains changes that have not been saved.
IsBufRW (hbuf)
Return True if the given buffer is read-write-able. This function returns False if the buffer is read-only.
MakeBufClip (hbuf, fClip)
If fClip is True, this turns the file buffer hbuf into a Clip buffer. Following this, the buffer will appear as a regular clip in the Clip Window.
If fClip is False, this turns the buffer into a regular, non-clip file buffer.
Clip buffers are automatically saved to the Clips subdirectory of the Source Insight program directory when
Source Insight exits.
NewBuf (name)
Creates a new empty file buffer and returns a handle to the file buffer (an hbuf). The name of the new buffer is specified by the name parameter. NewBuf returns hNil if the buffer could not be created due to errors.
OpenBuf (filename)
Opens a file named filename into a file buffer and returns a handle to the file buffer. OpenBuf returns hNil if the file could not be opened.
OpenMiscFile (filename)
Opens a file named filename. The action taken depends on the type of files opened. For example, opening a file with a .CF3 extension will load a new configuration file. Opening a project file (.PR extension) will open that project. OpenMiscFile returns TRUE if it was successful, or FALSE if not.
Source Insight 4 User Guide 389
File Buffer Functions
PasteBufLine (hbuf, ln)
Pastes the clipboad contents just before the line ln in the file buffer hbuf.
PrintBuf (hbuf, fUseDialogBox)
Prints the given file buffer on the printer. If fUseDialogBox is True, then the Print dialog box appears first.
Otherwise, the file prints with no user interaction on the default printer.
PutBufLine (hbuf, ln, s)
Replaces the line of text for line number ln in the file buffer hbuf with the string in s.
RenameBuf (hbuf, szNewName)
Renames the given buffer to szNewName. The file on disk is also renamed. If the buffer is a member of an open project, then the file is renamed in the project.
SaveBuf (hbuf)
Saves a file buffer to disk. Hbuf is the buffer handle.
SaveBufAs (hbuf, filename)
Saves a file buffer a different file name. Hbuf is the buffer handle. Filename is the name of the new file.
SetBufDirty (hbuf, fDirty)
Sets the dirty state of the given buffer to fDirty. A dirty buffer is one that has been edited since is was opened or saved. A dirty buffer contains changes that have not been saved.
When the user closes a dirty buffer, Source Insight prompts to save the file. You can use this function to undirty a buffer so that the user is not prompted to save it.
SetBufIns (hbuf, ln, ich)
Sets the cursor position insertion point to line number ln at character index ich in file buffer hbuf. A macro error is generated if the given file buffer is not already displayed in a source file window.
SetBufSelText (hbuf, s)
Replaces the currently selected characters in the file buffer hbuf with the string s. This is useful for replacing the text of a word selection. A macro error is generated if the given file buffer is not already displayed in a source file window.
This is the simplest way to insert new text into a buffer. For example, this code inserts "new text" into the current buffer at the current insertion position: hbuf = GetCurrentBuf()
SetBufSelText(hbuf, "new text")
SetCurrentBuf (hbuf)
Sets the active file buffer to the buffer whose handle is hbuf. The current buffer is the file buffer that appears in the front-most source file window.
390 Source Insight 4 User Guide