Utility functions for managing Text Objects. More...

Functions
static __inline__ const TEXT_OBJECT_VTABLE *	WBGetDefaultTextObjectVTable (void)
	returns the default vtable for a TEXT_OBJECT structure More...

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_BUFFER *	WBAllocTextBuffer (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...

int	WBTextBufferLineLength (TEXT_BUFFER *pBuf, unsigned long nLine)
	Text buffer 'cached information' query function indicating a line's cached length. 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...

void	WBTextObjectSetColorContextCallback (TEXT_OBJECT pThis, unsigned long(callback)(TEXT_OBJECT pThis, int nRow, int nCol), void pColorContextPointer)
	assign callback function for 'color context' for a given character More...

TEXT_OBJECT *	WBTextObjectConstructor (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...

Detailed Description

Utility functions for managing Text Objects.

Function Documentation

◆ WBAllocTextBuffer()

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

Generic constructor for a TEXT_BUFFER using defaults.

Parameters

pBuf	Optional initializer text. Can be NULL or 'blank', which will pre-allocate space for a default number of lines
cbBufSize	Length 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 320 of file text_object.c.

◆ WBCheckReAllocTextBuffer()

int WBCheckReAllocTextBuffer	(	TEXT_BUFFER **	ppBuf,
		int	nLinesToAdd
	)

Re-allocator for TEXT_BUFFER object.

Parameters

ppBuf	A pointer to a TEXT_BUFFER pointer that may be re-assigned (as needed).
nLinesToAdd	The 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 436 of file text_object.c.

◆ WBDestroyInPlaceTextObject()

static __inline__ void WBDestroyInPlaceTextObject ( TEXT_OBJECT * pTextObject )

static

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

Parameters

pTextObject A 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 1070 of file text_object.h.

◆ WBFreeTextBuffer()

void WBFreeTextBuffer ( TEXT_BUFFER * pBuf )

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

Parameters

pBuf	A 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 471 of file text_object.c.

◆ WBGetDefaultTextObjectVTable()

static __inline__ const TEXT_OBJECT_VTABLE* WBGetDefaultTextObjectVTable ( void )

static

returns the default vtable for a TEXT_OBJECT structure

Use this function to get a copy of the pointer to the default 'TEXT_OBJECT' vtable.

Definition at line 876 of file text_object.h.

◆ WBInitializeInPlaceTextObject()

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

static

initialize an 'in-place' TEXT_OBJECT structure

Parameters

pTextObject	A pointer to the TEXT_OBJECT structure to be initialized
wIDOwner	The 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 1045 of file text_object.h.

◆ WBIsValidTextObject()

static __inline__ int WBIsValidTextObject ( const TEXT_OBJECT * pObj )

static

'TEXT_OBJECT' validator

Parameters

pObj	A 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 1028 of file text_object.h.

◆ WBTextBufferLineChange()

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

pBuf	A pointer to a TEXT_BUFFER object
nLine	The 0-based line (row) number within the 'aLines' array
nNewLen	The new line length, or -1 if the line is being deleted.

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 516 of file text_object.c.

◆ WBTextBufferLineLength()

int WBTextBufferLineLength	(	TEXT_BUFFER *	pBuf,
		unsigned long	nLine
	)

Text buffer 'cached information' query function indicating a line's cached length.

Parameters

pBuf	A pointer to a TEXT_BUFFER object
nLine	The 0-based line (row) number within the 'aLines' array

Returns: The current cached length of the line.

This function returns the cached line length for the specified line. If you do something that might change this value, you can check first by calling this function to obtain the cached value, and then use WBTextBufferRefreshCache() to update it (as needed).

Header File: text_object.h

Definition at line 494 of file text_object.c.

◆ WBTextBufferRefreshCache()

void WBTextBufferRefreshCache ( TEXT_BUFFER * pBuf )

Text buffer 'cached information' refresh function.

Parameters

pBuf	A 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 691 of file text_object.c.

◆ WBTextObjectCalculateLineHeight()

int WBTextObjectCalculateLineHeight	(	int	iAscent,
		int	iDescent
	)

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

Parameters

iAscent	The 'ascent' for the display font
iDescent	The '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 864 of file text_object.c.

◆ WBTextObjectConstructor()

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

Generic constructor for a TEXT_OBJECT using defaults.

Parameters

cbStructSize	The size of the 'TEXT_OBJECT' structure itself
szText	The text to pre-assign the object with, or NULL
cbLen	The length of 'szText', 0 to indicate zero-byte terminated
wIDOwner	The 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 826 of file text_object.c.

◆ WBTextObjectDestructor()

void WBTextObjectDestructor ( TEXT_OBJECT * pObj )

Generic detructor for a TEXT_OBJECT.

Parameters

pObj	A 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 848 of file text_object.c.

◆ WBTextObjectSetColorContextCallback()

void WBTextObjectSetColorContextCallback	(	TEXT_OBJECT *	pThis,
		unsigned long()(TEXT_OBJECT pThis, int nRow, int nCol)	callback,
		void *	pColorContextPointer
	)

assign callback function for 'color context' for a given character

Parameters

pThis	A pointer to the TEXT_OBJECT structure
callback	A function pointer to a 'color context' callback function (see below). This value may be NULL.
pColorContextPointer	A pointer to non-specific user-maintained data. Its value will be stored in pColorContext. May be NULL.

Use 'WBTextObjectSetColorContextCallback()' to assign a color context callback function that returns the correct color of a character, given its row ('nRow') and column ('nCol') values, as a pixel (unsigned long) color value. The color context callback function should use the 'text object' pointer 'pThis' to perform whatever operations it needs to do in order to determine the correct color.

The color callback function should return the 'default' color (from the TEXT_OBJECT) when no specific color is to be assigned to a particular character. Otherwise it returns the correct 'XColor' pixel value based on the context-related color assignment.

The 'pColorContextPointer' value is stored directly as-is in the pColorContext member of the TEXT_OBJECT structure. It does not have to be a valid pointer (it can be a 'Window' cast to a pointer, for example). The value is simply available to the callback function whenever it is invoked, through the TEXT_OBJECT.

The callback function 'callback' will be invoked internally by passing a pointer to the TEXT_OBJECT as the first parameter, followed by the row and column values. The callback function must assume that a multi-byte character qualifies as a single column, and handle character spacing accordingly.

To notify the callback function that something has changed, it can be invoked with an 'nCol' value of -1. This should force the re-evaluation of all context colors starting with row 'nRow'. 'nRow' can also be a negative value to indicate that the entire file should be re-evaluated. Once completed, it should invalidate the window that is displaying the text, so that the correct colors will be painted. Additionally, any background thread that might be re-evaluating the context color should be re-startable (whenever the callback is re-invoked), and cause the window displaying the text object to be re-painted when complete.

Upon assignment, the callback will be evoked with 'nRow' and 'nCol' as -1, so that the re-evaluation will happen immediately. As such, it's usually important to assign the callback function before assigning any data.

Functions

Detailed Description

Function Documentation

◆ WBAllocTextBuffer()

◆ WBCheckReAllocTextBuffer()

◆ WBDestroyInPlaceTextObject()

◆ WBFreeTextBuffer()

◆ WBGetDefaultTextObjectVTable()

◆ WBInitializeInPlaceTextObject()

◆ WBIsValidTextObject()

◆ WBTextBufferLineChange()

◆ WBTextBufferLineLength()

◆ WBTextBufferRefreshCache()

◆ WBTextObjectCalculateLineHeight()

◆ WBTextObjectConstructor()

◆ WBTextObjectDestructor()

◆ WBTextObjectSetColorContextCallback()