Naming Conventions
In Source Insight, this statement would have to written like this: if (hbuf != hNil)
if (GetBufLineCount(hbuf) > x)
Naming Conventions
Variables and function parameters described in this macro guide are named using the following conventions.
Table 5.5: Identifier Naming Conventions
Name Meaning
s and sz ch ich ichFirst ichLast ichLim a string single character string. If more than one character is in a string, only the first character is used.
zero-based index to a character in a string or character in a line first index in a range of characters last index in a range of characters (inclusively) limit index - one past the last index in a range cch fThing count of characters
"f" means flag or boolean. fThing means "Thing" is
True.
a non-zero value, e.g. "1" TRUE
FALSE ln lnFirst lnLast lnLim hbuf hwnd hprj a zero value, i.e. "0" zero-based line number first line number in a range last line number in a range (inclusively) limit - one past the last line number in a range handle to a file buffer handle to a window handle to a project hsyml Handle to a symbol list
Any other names general string variables
Standard Record Structures
Record structures are similar to C data structures. A record variable is actually a delimited list of
"name=value" pairs. Record variables are used in the same way that a "struct" would be used in C. See
“Record Variables” on page 373.
Record variables are returned by some internal macro functions because it is a convenient way to return multiple values.
378 Source Insight 4 User Guide
Standard Record Structures
This section describes the record structures used by the internal macro functions in Source Insight.
Bookmark Record
A bookmark points to a position in a file. The Bookmark record has the following fields:
Field
Name
Description
The bookmark name.
File ln ich
Symbol
The file name of the bookmark position.
The line number position.
The character index on the line (zero based).
A nearby symbol definition to which the bookmark is anchored. This is usually the enclosing function or class.
The line number offset (distance) from Symbol.
lnOffset
SymbolType The type of Symbol.
FtpSiteName If the bookmark points to a file hosted on an FTP host, this is the "Site Name" used in the FTP Panel. If the bookmark points to a local file, then this field is empty.
FtpRemoteDir If the bookmark points to a file hosted on an FTP host, this is the remote directory name on the host. If the bookmark points to a local file, then this field is empty.
Bufprop Record
A Bufprop record contains file buffer properties. It is returned by
GetBufProps
. The Bufprop record has the following fields:
Field Description
Name fNew fDirty
DocumentType
The buffer name (i.e. file name)
True if buffer is a new, unsaved buffer.
True if the buffer has been edited since it was saved or opened.
fReadOnly fClip fMacro
True if the buffer is read-only.
True if the buffer is a clip that appears in the Clip Window.
True if the buffer is a macro file.
fRunningMacro True if the buffer is a currently running macro file.
fCaptureResults True if the buffer contains captured custom command output.
fSearchResults True if the buffer contains search results.
fProtected True if the buffer protected and reserved for internal use.
lnCount
Language
The line count of the buffer.
The programming language of the buffer. The language is determined by the file's document type.
The document type of the buffer.
Source Insight 4 User Guide 379
Standard Record Structures
DIM Record
The DIM record describes horizontal and vertical pixel dimensions.
Field
Cxp
Cyp
Description
Count of X-pixels (horizontal size)
Count of Y-pixels (vertical size)
Link Record
A Link record describes a location in a file, which is pointed to by a source link. The Link record has the following fields:
Field
File ln
Description
The file name
The line number - this is only valid for as long as the file is unchanged. If lines are inserted or deleted from the file, the line number is going to be off. However, you can call Get-
SourceLink again to get an updated line number.
ProgEnvInfo Record
The ProgEnvInfo record contains information about the environment where Source Insight is running.
Field
ProgramDir
TempDir
BackupDir
ClipDir
ProjectDirectoryFile
ConfigurationFile
MasterConfigurationFile
ShellCommand
UserName
UserOrganization
SerialNumber
Description
The Source Insight program directory, where the program file is stored.
The temporary files directory.
The backup directory, where Source Insight stores backups of files that you save.
The directory where clips are persisted.
The name of the project directory file. The project directory file contains a list of all the projects that have been opened.
The name of the currently active single configuration file. This entry will be empty if the master configuration file uses separate files for separate parts.
The name of the master configuration file.
The name of the command shell. The command shell depends on the operating system version you are running.
The registered user's name.
The registered user's organization.
The registered license serial number.
380 Source Insight 4 User Guide
Standard Record Structures
ProgInfo Record
The ProgInfo record describes the version of Source Insight that is running. It has the following fields:
Field
ProgramName versionMajor versionMinor versionBuild
CopyrightMsg fTrialVersion fBetaVersion
ExeFileName cchLineMax cchPathMax cchSymbolMax cchCmdMax cchBookmarkMax cchInputMax cchMacroStringMax lnMax integerMax integerMin
Description
The name of the program (i.e. "Source Insight")
The major version number. If the version number is 1.02.0003, then the major version is 1.
The minor version number. If the version number is 1.02.0003, then the major version is 2.
The build number of the version. If the version number is 1.02.0003, then the build number is 3.
The Source Dynamics copyright message.
True if the program is a Trial version.
True if the program is a Beta version.
The name of the executable file.
The maximum number of characters allowed in a source file line.
The maximum number of characters supported in a path name.
The maximum number of characters allowed in a symbol's full name.
The maximum number of characters allowed in a command, custom command, or macro command name.
The maximum number of characters allowed in a bookmark name.
The maximum number of characters allowed in a dialog box text input field.
The maximum number of characters allowed in a macro string variable.
The maximum number of lines supported in a source file.
The maximum integer value supported.
The minimum integer value supported (a negative number).
Rect Record
A Rect record describes the coordinates of a rectangle. The Rect records has the following fields:
Field
Left
Top
Right
Bottom
Description
The left pixel coordinate of the rectangle
The top pixel coordinate of the rectangle
The right pixel coordinate of the rectangle
The bottom pixel coordinate of the rectangle
Source Insight 4 User Guide 381
Standard Record Structures
Selection Record
A Selection record describes the state of a text selection in a window. The Selection record has the following fields:
Field Description
lnFirst ichFirst lnLast ichLim fExtended the last line number the limit index (one past the last) of the last character on the line given in lnLast
TRUE if the selection is extended to include more than one character. FALSE if the selection is a simple insertion point.
this is the same as the following expression:
(sel.fRect || sel.lnFirst != sel.lnLast || sel.ichFirst != sel.ich-
Lim) fRect TRUE if selection is rectangular (block style).
FALSE if the selection is a linear range of characters.
The following fields only apply if fRect is TRUE: xLeft the first line number the index of the first character on the line lnFirst xRight the left pixel position of the rectangle in window coordinates.
the pixel position of the right edge of the rectangle in window coordinates.
Symbol Record
The Symbol record describes a symbol declaration. It specifies the location and type of a symbol. It is used to uniquely describe a symbol in a project, or in an open file buffer.
Symbol records are returned by several functions, and Symbol records are used as input to several functions.
The Symbol record has the following fields:
Field
Symbol
Type
Project
File lnFirst lnLim lnName ichName
Instance
Description
The full symbol name. A symbol name is actually a path.
Every symbol name is divided into path components, which are separated by dot (.) characters. For example, a symbol name might be "myclass.member1". In this example, "member1" is contained by "myclass".
The symbol's type (e.g. "Function", "Class", etc.)
The full path of the project where the symbol was found
The full path of the file where the symbol was found
The first line number of the symbol declaration
The limit line number of the symbol declaration
The line number where the symbol's name appears in the declaration.
The character index of the symbol's name in the declaration at the line lnName.
The instance number path of the symbol within File. For example, the first occurrence of a symbol is instance 0, the second is instance 1, and so on.
382 Source Insight 4 User Guide