X11 Work Bench Toolkit  1.0
Text Editing Utilities and Objects

Generic utility functions and objects for editing text. More...

Data Structures

struct  _text_buffer_
 'base class' structure for TEXT_OBJECT More...
 
struct  _text_object_vtable_
 'vtable' structure for TEXT_OBJECT More...
 
struct  _text_object_
 'base class' structure for TEXT_OBJECT More...
 

Macros

#define HARD_TAB_CHAR   '\xa0'
 
#define DEFAULT_TAB_WIDTH   8
 
#define AUTO_HSCROLL_SIZE   8
 
#define MIN_LINE_SPACING   2
 
#define MIN_BORDER_SPACING   2
 
#define TEXT_OBJECT_TAG   (*((const unsigned int *)"WBTX"))
 The 'tag' for a TEXT_OBJECT structure.
 

Typedefs

typedef struct _text_buffer_ TEXT_BUFFER
 'base class' structure for TEXT_OBJECT More...
 
typedef struct _text_object_vtable_ TEXT_OBJECT_VTABLE
 'vtable' structure for TEXT_OBJECT More...
 
typedef struct _text_object_ TEXT_OBJECT
 'base class' structure for TEXT_OBJECT More...
 

Enumerations

enum  _FileType_ {
  FileType_MAKEFILE = -1, FileType_PLAIN_TEXT = 0, FileType_CLANG = 1, FileType_JAVA = 2,
  FileType_PERL = 3, FileType_PHP = 4, FileType_SHELL = 5, FileType_MASK = 0x7fff,
  FileType_HARDTAB = 0x10000, FileType_RESERVED2 = 0x20000, FileType_RESERVED3 = 0x40000, FileType_RESERVED4 = 0x80000
}
 file types for TEXT_OBJECT
 
enum  _LineFeed_ {
  LineFeed_NONE = -1, LineFeed_DEFAULT = 0, LineFeed_NEWLINE = 1, LineFeed_RETURN = 2,
  LineFeed_CRLF = 3, LineFeed_LFCR = 4, LineFeed_ENTRYCOUNT = 5
}
 line feed (line ending) types for TEXT_OBJECT More...
 
enum  _SelectMode_ { SelectMode_DEFAULT = 0, SelectMode_CHAR = 1, SelectMode_LINE = 2, SelectMode_BOX = 3 }
 select mode types for TEXT_OBJECT More...
 
enum  _InsertMode_ { InsertMode_DEFAULT = 0, InsertMode_INSERT = 1, InsertMode_OVERWRITE = 2 }
 Insert/Overwrite mode for TEXT_OBJECT. More...
 
enum  _DragState_ { DragState_NONE = 0, DragState_CURSOR = 1, DragState_MOUSE = 2 }
 State flags for mouse/cursor 'drag' (i.e. selection) More...
 

Functions

static __inline__ const
TEXT_OBJECT_VTABLE
WBGetDefaultTextObjectVTable (void)
 returns the default vtable for a TEXT_OBJECT structure
 
static __inline__ int WBIsValidTextObject (const TEXT_OBJECT *pObj)
 'TEXT_OBJECT' validator More...
 
static __inline__ void WBInitializeInPlaceTextObject (TEXT_OBJECT *pTextObject, Window wIDOwner)
 initialize an 'in-place' TEXT_OBJECT structure More...
 
static __inline__ void WBDestroyInPlaceTextObject (TEXT_OBJECT *pTextObject)
 Destroy a previously initialized 'in-place' TEXT_OBJECT structure. More...
 
TEXT_BUFFERWBAllocTextBuffer (const char *pBuf, unsigned int cbBufSize)
 Generic constructor for a TEXT_BUFFER using defaults. More...
 
int WBCheckReAllocTextBuffer (TEXT_BUFFER **ppBuf, int nLinesToAdd)
 Re-allocator for TEXT_BUFFER object. More...
 
void WBFreeTextBuffer (TEXT_BUFFER *pBuf)
 Re-allocator for TEXT_BUFFER object, returns ZERO on success. Pointer may be modified (or not). More...
 
void WBTextBufferLineChange (TEXT_BUFFER *pBuf, unsigned long nLine, int nNewLen)
 Text buffer 'cached information' update function indicating a change to a line's length. More...
 
void WBTextBufferRefreshCache (TEXT_BUFFER *pBuf)
 Text buffer 'cached information' refresh function. More...
 
TEXT_OBJECTWBTextObjectConstructor (unsigned long cbStructSize, const char *szText, unsigned long cbLen, Window wIDOwner)
 Generic constructor for a TEXT_OBJECT using defaults. More...
 
void WBTextObjectDestructor (TEXT_OBJECT *pObj)
 Generic detructor for a TEXT_OBJECT. More...
 
int WBTextObjectCalculateLineHeight (int iAscent, int iDescent)
 Calculate the correct per-line height (in pixels) for a specified font ascent and descent. More...
 
char * WBInsertMBChars (char *pString, int iCol, const char *pszMBString, int cbString, int fTab, int fOverwrite, int *piNewCol, char **ppInserted)
 Insert multi-byte characters into a WBAlloc'd string, at a specified column. More...
 
char * WBSplitMBLine (char *pString, int iCol)
 Split a multi-byte characters into a WBAlloc'd string, at a specified column, terminating the original string at that column with a zero byte. More...
 
char * WBJoinMBLine (char *pString, int iCol, const char *pJoin)
 Split a multi-byte characters into a WBAlloc'd string, at a specified column, terminating the original string at that column with a zero byte. More...
 
int WBDelMBChars (char *pString, int iCol, int nDel, int *piNewCol, char **ppDeleted)
 Delete a specified number of multi-byte characters from a string 'in place', starting at a specified column. More...
 
int WBGetMBLength (const char *pString)
 Obtain the length of a multi-byte character string in 'characters' (not bytes) More...
 
char * WBGetMBCharPtr (char *pString, int iCol, int *pcbLen)
 Obtain the pointer to a specific multi-byte character within a multi-byte character string, by specifying it's column. More...
 
int WBGetMBColIndex (const char *pString, const char *pChar)
 Obtain the column index from a pointer within a multi-byte character string. More...
 

Detailed Description

Generic utility functions and objects for editing text.

Text editing utilities and objects encapsulate the basic functionality of editing text, such as text selection (character, line, or box), as well as inserting, overwriting, deleting, replacing, and rendering edited text. The utilities are 'line based' and intended to display text within a window of character-based dimensions with a specified X,Y scroll position and a fixed-width font.

See Also
Edit Window APIs and Structures

Macro Definition Documentation

#define AUTO_HSCROLL_SIZE   8

the number of characters to auto-hscroll by to get the cursor inside the viewport

Definition at line 145 of file text_object.h.

#define DEFAULT_TAB_WIDTH   8

the default width for a hard tab in a TEXT_OBJECT

Definition at line 141 of file text_object.h.

#define HARD_TAB_CHAR   '\xa0'

A 'hard tab' is represented internally by this character

Definition at line 137 of file text_object.h.

#define MIN_BORDER_SPACING   2

the minimum number of pixels separating the text from the window border (when unspecified)

Definition at line 153 of file text_object.h.

#define MIN_LINE_SPACING   2

the minimum number of pixels by which lines are separated (normally will be 'descent / 2')

Definition at line 149 of file text_object.h.

Typedef Documentation

typedef struct _text_buffer_ TEXT_BUFFER

'base class' structure for TEXT_OBJECT

typedef struct _text_buffer_
{
unsigned long nArraySize; // allocated size of aLines array
unsigned long nEntries; // number of entries currently in the array
// cached information
unsigned int nMaxCol; // The maximum column number for any line, rounded up by 'DEFAULT_TAB_WIDTH'
unsigned int nMinMaxCol; // The 'smallest maximum' recorded in 'aLineCache'
unsigned long aLineCache[TEXT_BUFFER_LINE_CACHE_SIZE];
// An array of line indices, sorted longest to least, for the 'longest lines'
unsigned int aLineCacheLen[TEXT_BUFFER_LINE_CACHE_SIZE];
// The actual line lengths associated with 'aLineCache' (zero if unused)
char * aLines[2]; // array of 'lines' suballocated via WBAlloc()

The structure is assumed to have a variable length array 'aLines' at the end, which extends beyond the length of the base structure. 'nArraySize' indicates the maximum size of this array, and 'nEntries' indicates the (contiguous) actual size of the array, starting at element [0].
This is a simple array structure, and to insert a line in the middle you will need to use 'memmove()' following a call to WBCheckReAllocTextBuffer(), and then re-assign 'nEntries' as needed. New entries must be allocated via 'WBAlloc()'.
To allocate a new structure, call WBAllocTextBuffer(). To free an allocated structure, call WBFreeTextBuffer().
The 'cached information' data members are maintained internally. You should not alter them. You can re-evaluate them at any time by calling WBTextBufferLineChange() and WBTextBufferRefreshCache()

'base class' structure for TEXT_OBJECT

typedef struct _text_object_
{
const TEXT_OBJECT_VTABLE *vtable; // method function pointers (similar to C++ virtual members)
unsigned int ulTag; // tag word, always assigned to TEXT_OBJECT_TAG
Window wIDOwner; // owner window (cached from paint/expose handling and/or cursor blink)
WB_RECT rctSel; // select boundary in characters
WB_RECT rctHighLight; // highlight rect
XColor clrHFG; // highlight FG color
XColor clrHBG; // highlight BG color
int iFileType; // file type - -1=Makefile, 0=plain text, others are 'file type' constants
enum _LineFeed_ iLineFeed; // linefeed type (see enum)
int iInsMode; // insert mode - 0=overwrite, 1=insert
int iSelMode; // selection mode - 0=normal, 1=line, 2=box
int iScrollMode; // scroll mode - 0=normal, 1='scroll lock'
int iTab; // tab width in characters (0 = system default)
// cursor position
int iRow; // current row (cursor)
int iCol; // current col (cursor)
int iPos; // position within buffer
int iCursorX; // X position of cursor as last drawn in expose event
int iCursorY; // Y position of cursor as last drawn in expose event (top of cursor)
int iCursorHeight; // height of cursor as last drawn in expose event
int iBlinkState; // cursor blink state
int iDragState; // if '1' bit is set, cursor drag. if '2' bit is set, mouse drag
int iAsc; // font height ascension (cached)
int iDesc; // font height descension (cached)
int iFontWidth; // width of font in pixels (fixed pitch) - cached by 'expose' handler
// viewport
WB_RECT rctView; // viewport, in characters
WB_RECT rctWinView; // viewport, in window coordinates, or 'empty' if unknown
// the data
void *pText; // pointer to (abstracted) object containing the text. void pointer
// allows abstraction. member functions must handle correctly
void *pUndo; // pointer to 'undo' buffer. NULL if empty.
void *pRedo; // pointer to 'redo' buffer. NULL if empty.

'vtable' structure for TEXT_OBJECT

typedef struct _text_object_vtable_
{
void (* destroy)(struct _text_object_ *pThis);
void (* init)(struct _text_object_ *pThis);
void (* highlight_colors)(struct _text_object_ *pThis, XColor clrHFG, XColor clrHBG);
char * (* get_text)(struct _text_object_ *pThis);
void (* set_text)(struct _text_object_ *pThis, const char *szText, unsigned long cbLen);
int (* get_rows)(const struct _text_object_ *pThis);
int (* get_cols)(struct _text_object_ *pThis);
int (* get_filetype)(const struct _text_object_ *pThis);
void (* set_filetype)(struct _text_object_ *pThis, int iLineFeed);
int (* get_linefeed)(const struct _text_object_ *pThis);
void (* set_linefeed)(struct _text_object_ *pThis, int iLineFeed);
int (* get_insmode)(const struct _text_object_ *pThis);
void (* set_insmode)(struct _text_object_ *pThis, int iInsMode);
int (* get_selmode)(const struct _text_object_ *pThis);
void (* set_selmode)(struct _text_object_ *pThis, int iSelMode);
int (* get_tab)(const struct _text_object_ *pThis);
void (* set_tab)(struct _text_object_ *pThis, int iTab);
int (* get_scrollmode)(const struct _text_object_ *pThis);
void (* set_scrollmode)(struct _text_object_ *pThis, int iScrollMode);
void (* get_select)(const struct _text_object_ *pThis, WB_RECT *pRct);
void (* set_select)(struct _text_object_ *pThis, const WB_RECT *pRct);
int (* has_select)(struct _text_object_ *pThis);
char* (* get_sel_text)(const struct _text_object_ *pThis, const WB_RECT *pRct);
int (* get_row)(const struct _text_object_ *pThis);
void (* set_row)(struct _text_object_ *pThis, int iRow);
int (* get_col)(const struct _text_object_ *pThis);
void (* set_col)(struct _text_object_ *pThis, int iCol);
void (* del_select)(struct _text_object_ *pThis);
void (* replace_select)(struct _text_object_ *pThis, const char *szText, unsigned long cbLen);
void (* del_chars)(struct _text_object_ *pThis, int nChar);
void (* ins_chars)(struct _text_object_ *pThis, const char *pChar, int nChar);
void (* indent)(struct _text_object_ *pThis, int nCol);
int (* can_undo)(struct _text_object_ *pThis);
void (* undo)(struct _text_object_ *pThis);
int (* can_redo)(struct _text_object_ *pThis);
void (* redo)(struct _text_object_ *pThis);
void (* get_view)(const struct _text_object_ *pThis, WB_RECT *pRct);
void (* set_view)(struct _text_object_ *pThis, const WB_RECT *pRct);
void (* begin_highlight)(struct _text_object_ *pThis);
void (* end_highlight)(struct _text_object_ *pThis);
// mouse conversion
void (* mouse_click)(struct _text_object_ *pThis, int iMouseXDelta, int iMouseYDelta, int iType, int iACS);
void (* begin_mouse_drag)(struct _text_object_ *pThis);
void (* end_mouse_drag)(struct _text_object_ *pThis);
// cursor motion
void (* cursor_up)(struct _text_object_ *pThis);
void (* cursor_down)(struct _text_object_ *pThis);
void (* cursor_left)(struct _text_object_ *pThis);
void (* cursor_right)(struct _text_object_ *pThis);
void (* page_up)(struct _text_object_ *pThis);
void (* page_down)(struct _text_object_ *pThis);
void (* page_left)(struct _text_object_ *pThis);
void (* page_right)(struct _text_object_ *pThis);
void (* cursor_home)(struct _text_object_ *pThis);
void (* cursor_end)(struct _text_object_ *pThis);
void (* cursor_top)(struct _text_object_ *pThis);
void (* cursor_bottom)(struct _text_object_ *pThis);
// handling expose events for the text area
void (* do_expose)(const struct _text_object_ *pThis, Display *pDisplay, Window wID,
GC gc, const WB_GEOM *pPaintGeom, const WB_GEOM *pViewGeom,
XFontSet rFontSet);
void (* cursor_blink)(struct _text_object_ *pThis, int bHasFocus);

Enumeration Type Documentation

State flags for mouse/cursor 'drag' (i.e. selection)

Enumerator
DragState_NONE 

no drag in progress

DragState_CURSOR 

cursor 'drag' (select mode)

DragState_MOUSE 

mouse 'drag' (select mode)

Definition at line 128 of file text_object.h.

Insert/Overwrite mode for TEXT_OBJECT.

Enumerator
InsertMode_DEFAULT 

system default, usually 'insert'

InsertMode_INSERT 

INSERT mode, character inserted at cursor.

InsertMode_OVERWRITE 

OVERWRITE mode, character inserted on top of character to the right of the cursor (if any), else inserted.

Definition at line 118 of file text_object.h.

enum _LineFeed_

line feed (line ending) types for TEXT_OBJECT

Enumerator
LineFeed_NONE 

single line

LineFeed_DEFAULT 

default for OS

LineFeed_NEWLINE 

POSIX newline 0AH.

LineFeed_RETURN 

OSX return 0DH.

LineFeed_CRLF 

CRLF 0DH,0AH.

LineFeed_LFCR 

LFCR 0AH,0DH.

LineFeed_ENTRYCOUNT 

size of array containing values, excluding negative indices

Definition at line 93 of file text_object.h.

select mode types for TEXT_OBJECT

Enumerator
SelectMode_DEFAULT 

DEFAULT (typically CHAR)

SelectMode_CHAR 

CHAR (i.e. stream)

SelectMode_LINE 

LINE (always selects entire line when spanning multiple lines)

SelectMode_BOX 

BOX (selects a 'box' using virtual spacing)

Definition at line 107 of file text_object.h.

Function Documentation

TEXT_BUFFER* WBAllocTextBuffer ( const char *  pBuf,
unsigned int  cbBufSize 
)

Generic constructor for a TEXT_BUFFER using defaults.

Parameters
pBufOptional initializer text. Can be NULL or 'blank', which will pre-allocate space for a default number of lines
cbBufSizeLength of data pointed to by 'pBuf'. Zero implies zero-byte terminated string
Returns
A 'WBAlloc'd pointer to a TEXT_BUFFER object. Use 'WBFreeTextBuffer' to free it safely.

Header File: text_object.h

Definition at line 278 of file text_object.c.

int WBCheckReAllocTextBuffer ( TEXT_BUFFER **  ppBuf,
int  nLinesToAdd 
)

Re-allocator for TEXT_BUFFER object.

Parameters
ppBufA pointer to a TEXT_BUFFER pointer that may be re-assigned (as needed).
nLinesToAddThe number of additional lines that need to be added [or have space reserved for]
Returns
A non-zero value on error, or zero on success

Header File: text_object.h

Definition at line 385 of file text_object.c.

int WBDelMBChars ( char *  pString,
int  iCol,
int  nDel,
int *  piNewCol,
char **  ppDeleted 
)

Delete a specified number of multi-byte characters from a string 'in place', starting at a specified column.

Parameters
pStringA pointer to a buffer containing a multi-byte character string. The string must terminate with a zero byte.
iColA zero-based column at which point to delete the text.
nDelAn integer indicating the number of multi-byte characters to delete. A negative number will delete 'backspace' style, starting with the PREVIOUS character. Positive deletes beginning with the character at 'iCol'.
piNewColAn optional pointer to an integer that receives the new column that the cursor is on after the operation completes. May be NULL.
ppDeletedAn optional pointer to a char * that will be assigned a WBAlloc'd pointer to a string containing the deleted characters. May be NULL. The caller must free any non-NULL returned value via WBFree()
Returns
The number of deletions remaining (preserving the sign of 'nDel') after the operation completes.

This function performs the somewhat complicated 'delete a multi-byte character' functionality in a consistent AND column-based manner, so that a string that has multi-byte characters can be edited in the same way as a string that has characters with consistent length. It also returns the number of delete operations remaining.

In many cases, a series of 'backspaces' or 'deletes' may extend into a previous or subsequent line. In these cases, they must be handled in a separate call involving the previous or next line's multi-byte character buffer. The caller is responsible for handlnig this, as well as for collapsing the lines or joining them together.

If a 'ppDeleted' pointer value is specified, this function will store the deleted text in a buffer allocated via WBAlloc(). The caller must free any non-NULL value returned by this function using WBFree(). The data that is stored in this allocated buffer can be used to support 'undo' and 'redo'.

Header File: text_object.h

Definition at line 5337 of file text_object.c.

static __inline__ void WBDestroyInPlaceTextObject ( TEXT_OBJECT pTextObject)
static

Destroy a previously initialized 'in-place' TEXT_OBJECT structure.

Parameters
pTextObjectA pointer to the TEXT_OBJECT structure to be initialized

Use this function to destroy an in-place TEXT_OBJECT that is an automatic variable or a part of an array.

See Also
WBInitializeInPlaceTextObject()

Header File: text_object.h

Definition at line 947 of file text_object.h.

void WBFreeTextBuffer ( TEXT_BUFFER pBuf)

Re-allocator for TEXT_BUFFER object, returns ZERO on success. Pointer may be modified (or not).

Parameters
pBufA pointer to a TEXT_BUFFER that has been previously allocated. It assumes that valid 'aLines' entries contain pointers allocated via 'WBAlloc'
Returns
void

Header File: text_object.h

Definition at line 420 of file text_object.c.

char* WBGetMBCharPtr ( char *  pString,
int  iCol,
int *  pcbLen 
)

Obtain the pointer to a specific multi-byte character within a multi-byte character string, by specifying it's column.

Parameters
pStringA pointer to a buffer containing a multi-byte character string. The string must terminate with a zero byte.
iColA zero-based column at which point to return a pointer to the multi-byte character
pcbLenA pointer to an integer that receives the length of the character being pointed to by the return value. This pointer may be NULL
Returns
A pointer to the multi-byte character located at the 'iCol' position within the string. If 'iCol' is out range, the return value will point to the terminating zero byte. On error, the return value will be NULL.

Header File: text_object.h

Definition at line 5511 of file text_object.c.

int WBGetMBColIndex ( const char *  pString,
const char *  pChar 
)

Obtain the column index from a pointer within a multi-byte character string.

Parameters
pStringA pointer to a buffer containing a multi-byte character string. The string must terminate with a zero byte.
pCharA (const) pointer to a character within 'pString'. This must be a pointer to the start of a valid UTF-8 character within 'pString'.
Returns
The zero-based column index of the character pointed to by 'pChar' within 'pString. If 'pChar' is out range, or points to an invalid character, the return value will be zero.

Header File: text_object.h

Definition at line 5543 of file text_object.c.

int WBGetMBLength ( const char *  pString)

Obtain the length of a multi-byte character string in 'characters' (not bytes)

Parameters
pStringA pointer to a buffer containing a multi-byte character string. The string must terminate with a zero byte.
Returns
The length of the multi-byte character string in 'characters'

Header File: text_object.h

Definition at line 5501 of file text_object.c.

static __inline__ void WBInitializeInPlaceTextObject ( TEXT_OBJECT pTextObject,
Window  wIDOwner 
)
static

initialize an 'in-place' TEXT_OBJECT structure

Parameters
pTextObjectA pointer to the TEXT_OBJECT structure to be initialized
wIDOwnerThe owning window's Window ID. Can be 'None'

Use this function to initialize a TEXT_OBJECT as an automatic variable or as part of an array.

Make sure you call WBDestroyInPlaceTextObject() right before de-allocating it.

Header File: text_object.h

Definition at line 922 of file text_object.h.

char* WBInsertMBChars ( char *  pString,
int  iCol,
const char *  pszMBString,
int  cbString,
int  fTab,
int  fOverwrite,
int *  piNewCol,
char **  ppInserted 
)

Insert multi-byte characters into a WBAlloc'd string, at a specified column.

Parameters
pStringA pointer to a WBAlloc'd buffer containing a multi-byte character string. The string must terminate with a zero byte.
iColA zero-based column at which point to insert the text.
pszMBStringA pointer to a buffer containing the multi-byte characters to insert. It must NOT contain any return or line feed characters. Tabs will be translated as specified. Other control characters will become spaces (including line feeds, if present)
cbStringThe length of the multi-byte character string (in bytes, not characters), or -1 to use a terminating zero byte as 'end of string'
fTabAn integer indicating how tabs should be handled. A value of 0 indicates 'no tabs', '-1' is the 'default' tab, and any other value, the number of spaces that a tab will align with.
fOverwriteNon-zero to 'overwrite' rather than insert the characters. Overwrite can extend the length of the string.
piNewColA pointer to an integer to receive the 0-based 'new' column at which the cursor is pointing after the insert. See 'WBSplitMBLine()' for a method to insert a line feed at this point.
ppInsertedAn optional pointer to a char * that will be assigned a WBAlloc'd pointer to a string containing the inserted characters. May be NULL. The caller must free any non-NULL returned value via WBFree()
Returns
A pointer to a WBAlloc'd string containing the results. If different from 'pString', the 'pString' pointer value will no longer be valid. On error, it will return NULL

This function performs the somewhat complicated 'insert a multi-byte character' functionality in a consistent AND column-based manner, so that a string that has multi-byte characters can be edited in the same way as a string that has characters with consistent length. In this way, ANY multi-byte character that is available at a future point in time can be supported. The alternative would be to convert to "a unicode format", which may limit the character set that could be used; as an example, 16-bit unicode characters won't include characters that are available in the 24-bit Unicode character set. Having a ridiculously large bit-length for a single character is not much of a consolation, and so this function (and others) will deal with multiple byte characters as they are, in an independent manner.

It is the caller's responsibility to filter out line feed characters, and insert new lines into a line buffer.

If a 'ppInserted' pointer value is specified, this function will store the inserted text in a buffer allocated via WBAlloc(). The caller must free any non-NULL value returned by this function using WBFree(). The data that is stored in this allocated buffer can be used to support 'undo' and 'redo'.

Header File: text_object.h

Definition at line 5243 of file text_object.c.

static __inline__ int WBIsValidTextObject ( const TEXT_OBJECT pObj)
static

'TEXT_OBJECT' validator

Parameters
pObjA const pointer to a (possible) TEXT_OBJECT structure
Returns
non-zero if the object is a valid TEXT_OBJECT, zero otherwise

Header File: text_object.h

Definition at line 905 of file text_object.h.

char* WBJoinMBLine ( char *  pString,
int  iCol,
const char *  pJoin 
)

Split a multi-byte characters into a WBAlloc'd string, at a specified column, terminating the original string at that column with a zero byte.

Parameters
pStringA pointer to a WBAlloc'd buffer containing a multi-byte character string. The string must terminate with a zero byte.
iColA 0-based column index value. If the value is greater than the length of 'pString', then 'pString' will be padded with spaces up to that column before 'joining'.
pJoinA (const) poitner to a buffer containing a multi-byte character string, terminated with a zero byte. This
Returns
A pointer to a WBAlloc'd string containing the resulting 'join'ed string. If different from 'pString', the 'pString' pointer value will no longer be valid. On error, it will return NULL

This function will 'join' a 2nd string to an existing (WBAlloc'd) multi-byte character string, optionally at a specified column (padding it with white space, as needed). The 'pString' pointer must have been allocated via WBAlloc for this to function properly. However, the 'pJoin' string can be from any source.

The caller is expected to remove the subsequent string pointer from being the 'next' line, as needed, following the line join.

Definition at line 5300 of file text_object.c.

char* WBSplitMBLine ( char *  pString,
int  iCol 
)

Split a multi-byte characters into a WBAlloc'd string, at a specified column, terminating the original string at that column with a zero byte.

Parameters
pStringA pointer to a WBAlloc'd buffer containing a multi-byte character string. The string must terminate with a zero byte.
iColA zero-based column at which point to split the line.
Returns
A pointer to a WBAlloc'd string containing the next line to insert. On error, it will return NULL without any changes being made.

This function will 'split' a string at a particular column, returning a WBAlloc'd pointer to the 'remainder' of the line, which is intended to be inserted as a new line. The new line will NOT be indented, and leading white space will be left 'as-is'. Trailing white space on the original line, however, will automatically be trimmed.

The caller is expected to insert the returned string pointer as the 'next' line, following the line split. The caller is also responsible for any 'auto indent' functionality that might be needed for a line split.

Definition at line 5263 of file text_object.c.

void WBTextBufferLineChange ( TEXT_BUFFER pBuf,
unsigned long  nLine,
int  nNewLen 
)

Text buffer 'cached information' update function indicating a change to a line's length.

Parameters
pBufA pointer to a TEXT_BUFFER object
nLineThe 0-based line (row) number within the 'aLines' array
nNewLenThe new line length, or -1 if the line is being deleted.
Returns
void

Whenever you modify the length of a line, or delete a line, you should call this function to automatically update the internally cached information specifying the maximum column number.
For complex edits, use WBTextBufferRefreshCache().
If you join a pair of lines, call this function once for the deleted line, then again for the new (joined) line.

Header File: text_object.h

Definition at line 443 of file text_object.c.

void WBTextBufferRefreshCache ( TEXT_BUFFER pBuf)

Text buffer 'cached information' refresh function.

Parameters
pBufA pointer to a TEXT_BUFFER object
Returns
void

Call this function to completely re-evaluate the cached information regarding line lengths. In some cases this can be time-consuming, but on a modern processor it's not likely to be noticable for documents smaller than 1Mb in size.
You should call this function following an 'undo' or other complex edit operation, in lieu of WBTextBufferLineChange(). Also, for single-line edits, it may be better to ALWAYS use this function.

Header File: text_object.h

Definition at line 584 of file text_object.c.

int WBTextObjectCalculateLineHeight ( int  iAscent,
int  iDescent 
)

Calculate the correct per-line height (in pixels) for a specified font ascent and descent.

Parameters
iAscentThe 'ascent' for the display font
iDescentThe 'descent' for the display font
Returns
A calculated line height (in pixels) that includes the line spacing.

Use this function to consistently get the line height from font information. The Text Object expose handler uses this calculation exclusively. Sometimes owning objects need to know exactly how this is being calculated to properly handle scrolling, etc. and this function returns the same results that the expose handler will use to determine where to draw text in the display geometry.

Header File: text_object.h

Definition at line 742 of file text_object.c.

TEXT_OBJECT* WBTextObjectConstructor ( unsigned long  cbStructSize,
const char *  szText,
unsigned long  cbLen,
Window  wIDOwner 
)

Generic constructor for a TEXT_OBJECT using defaults.

Parameters
cbStructSizeThe size of the 'TEXT_OBJECT' structure itself
szTextThe text to pre-assign the object with, or NULL
cbLenThe length of 'szText', 0 to indicate zero-byte terminated
wIDOwnerThe owner window in which to display the text, or 'None'
Returns
A 'WBAlloc'd and initialized TEXT_OBJECT pointer - call WBTextObjectDestructor to destroy it

This is being implemented as an object, similar to a C++ class with virtual member functions, for the purpose of being able to re-assign the vtable and thereby overload its functionality.

Header File: text_object.h

Definition at line 710 of file text_object.c.

void WBTextObjectDestructor ( TEXT_OBJECT pObj)

Generic detructor for a TEXT_OBJECT.

Parameters
pObjA pointer to the TEXT_OBJECT structure
Returns
void

Use this function to SAFELY destroy an object allocated using WBTextObjectConstructor

Header File: text_object.h

Definition at line 732 of file text_object.c.