MiniGUI API Reference (MiniGUI-Threads)  v3.2.0
A mature and proven cross-platform GUI system for embedded and smart IoT devices
Data Structures | Macros | Functions
Text parsing functions

Data Structures

struct  _WORDINFO
 

Macros

#define MB2WC(log_font, dest, mstr, n)   MB2WCEx (log_font, dest, sizeof(wchar_t) == 4, mstr, n)
 The backward compatibility version of MB2WCEx. More...
 
#define WC2MB(log_font, s, wc)   WC2MBEx (log_font, s, (UChar32)wc)
 The backward compatibility version of WC2MBEx. More...
 
#define MBS2WCS(log_font, dest, mstr, mstr_len, n)
 The backward compatibility version of MBS2WCSEx. More...
 
#define WCS2MBS(log_font, dest, wcs, wcs_len, n)
 The backward compatibility version of WCS2MBSEx. More...
 

Functions

MG_EXPORT int GUIAPI GetTextMCharInfo (PLOGFONT log_font, const char *mstr, int len, int *pos_chars)
 Retrieves positions of multi-byte characters in a string. More...
 
MG_EXPORT int GUIAPI GetTextWordInfo (PLOGFONT log_font, const char *mstr, int len, int *pos_words, WORDINFO *info_words)
 Retrieves information of multi-byte words in a string. More...
 
MG_EXPORT int GUIAPI GetFirstMCharLen (PLOGFONT log_font, const char *mstr, int len)
 Retrieves the length of the first multi-byte character in a string. More...
 
MG_EXPORT int GUIAPI GetFirstWord (PLOGFONT log_font, const char *mstr, int len, WORDINFO *word_info)
 Retrieves the length and info of the first multi-byte word in a string. More...
 
MG_EXPORT int GUIAPI MB2WCEx (PLOGFONT log_font, void *dest, BOOL wc32, const unsigned char *mstr, int n)
 Converts a multibyte character to a wide character in UCS according to the charset/encoding of the logical font. More...
 
MG_EXPORT int GUIAPI WC2MBEx (PLOGFONT log_font, unsigned char *s, UChar32 wc)
 Converts a wide character in UCS to a multibyte character according to the charset/encoding of the logical font. More...
 
MG_EXPORT int GUIAPI MBS2WCSEx (PLOGFONT log_font, void *dest, BOOL wc32, const unsigned char *mstr, int mstr_len, int n, int *conved_mstr_len)
 Converts a multibyte string to a wide character string in UC16 according to the charset/encoding of the logical font. More...
 
MG_EXPORT int GUIAPI WCS2MBSEx (PLOGFONT log_font, unsigned char *dest, const void *wcs, int wcs_len, BOOL wc32, int n, int *conved_wcs_len)
 Converts a wide character string in UC16 to a multibyte string according to the charset/encoding of the logical font. More...
 
MG_EXPORT int GUIAPI GetTextExtentPoint (HDC hdc, const char *text, int len, int max_extent, int *fit_chars, int *pos_chars, int *dx_chars, SIZE *size)
 Computes the extent of a string when output the string in a limited space. More...
 
MG_EXPORT int GUIAPI GetTabbedTextExtentPoint (HDC hdc, const char *text, int len, int max_extent, int *fit_chars, int *pos_chars, int *dx_chars, SIZE *size)
 Computes the extent of a string when output the formatted string in a limited space. More...
 

Detailed Description

MiniGUI uses logical font to output text, also uses logical font to parsing the multi-byte characters and words in the text.

Macro Definition Documentation

#define MB2WC (   log_font,
  dest,
  mstr,
 
)    MB2WCEx (log_font, dest, sizeof(wchar_t) == 4, mstr, n)

The backward compatibility version of MB2WCEx.

See also
MB2WCEx

Definition at line 6582 of file gdi.h.

#define MBS2WCS (   log_font,
  dest,
  mstr,
  mstr_len,
 
)
Value:
MBS2WCSEx(log_font, dest, sizeof (wchar_t) == 4, mstr, \
mstr_len, n, NULL)
MG_EXPORT int GUIAPI MBS2WCSEx(PLOGFONT log_font, void *dest, BOOL wc32, const unsigned char *mstr, int mstr_len, int n, int *conved_mstr_len)
Converts a multibyte string to a wide character string in UC16 according to the charset/encoding of t...
#define NULL
A value indicates null pointer.
Definition: common.h:320

The backward compatibility version of MBS2WCSEx.

See also
MBS2WCSEx

Definition at line 6655 of file gdi.h.

#define WC2MB (   log_font,
  s,
  wc 
)    WC2MBEx (log_font, s, (UChar32)wc)

The backward compatibility version of WC2MBEx.

See also
WC2MBEx

Definition at line 6610 of file gdi.h.

#define WCS2MBS (   log_font,
  dest,
  wcs,
  wcs_len,
 
)
Value:
WCS2MBSEx (log_font, dest, wcs, wcs_len, sizeof (wchar_t) == 4, \
n, NULL)
MG_EXPORT int GUIAPI WCS2MBSEx(PLOGFONT log_font, unsigned char *dest, const void *wcs, int wcs_len, BOOL wc32, int n, int *conved_wcs_len)
Converts a wide character string in UC16 to a multibyte string according to the charset/encoding of t...
#define NULL
A value indicates null pointer.
Definition: common.h:320

The backward compatibility version of WCS2MBSEx.

See also
WCS2MBSEx

Definition at line 6701 of file gdi.h.

Function Documentation

MG_EXPORT int GUIAPI GetFirstMCharLen ( PLOGFONT  log_font,
const char *  mstr,
int  len 
)

Retrieves the length of the first multi-byte character in a string.

This function retrieves and returns the length of the first multi-byte character in the string mstr which is len bytes long.

Parameters
log_fontThe logical font used to parse the multi-byte string.
mstrThe multi-byte string.
lenThe length of the string.
Returns
The length of the first multi-byte character.
See also
GetFirstWord
MG_EXPORT int GUIAPI GetFirstWord ( PLOGFONT  log_font,
const char *  mstr,
int  len,
WORDINFO word_info 
)

Retrieves the length and info of the first multi-byte word in a string.

This function retrieves the information of the first multi-byte character in the string mstr which is len bytes long, and returns it through word_info. It also returns the full length of the word including the delimiters after the word.

Parameters
log_fontThe logical font used to parse the multi-byte string.
mstrThe multi-byte string.
lenThe length of the string.
word_infoThe pointer to a WORDINFO structure used to return the word information.
Returns
The length of the first multi-byte word.
See also
GetFirstMCharLen, WORDINFO
int GUIAPI GetTabbedTextExtentPoint ( HDC  hdc,
const char *  text,
int  len,
int  max_extent,
int *  fit_chars,
int *  pos_chars,
int *  dx_chars,
SIZE size 
)

Computes the extent of a string when output the formatted string in a limited space.

int GUIAPI GetTextExtentPoint ( HDC  hdc,
const char *  text,
int  len,
int  max_extent,
int *  fit_chars,
int *  pos_chars,
int *  dx_chars,
SIZE size 
)

Computes the extent of a string when output the string in a limited space.

This function computes the extent of the specified string of text text which is len bytes long when output the text in a limited space (max_extent wide). If pos_chars and dx_chars are not NULL, this function will return the positions of each character in the text, and the output position of each character. This function returns the text extent in a SIZE struct pointed to by size, and the width of text as return value.

Parameters
hdcThe device context.
textThe multi-byte string.
lenThe length of the string.
max_extentThe width of the limited space.
fit_charsThe number of the characters actually outputed.
pos_charsThe positions of each character in the text will be returned through this pointer.
dx_charsThe output positions of each character in the text will be returned through this pointer.
sizeThe output extent of the text in the limited space will be returned through this pointer.
Returns
The number of the characters which can be fit to the limited space.
See also
GetFirstMCharLen, GetFirstWord
MG_EXPORT int GUIAPI GetTextMCharInfo ( PLOGFONT  log_font,
const char *  mstr,
int  len,
int *  pos_chars 
)

Retrieves positions of multi-byte characters in a string.

This function retrieves position of multi-byte characters in the string mstr which is len bytes long. It returns the positions of characters in the string in an integer array pointed to by pos_chars.

Parameters
log_fontThe logical font used to parse the multi-byte string.
mstrThe multi-byte string.
lenThe length of the string.
pos_charsThe position of characters will be returned through this array if it is not NULL.
Returns
The number of characters in the multi-byte string.
See also
GetTextWordInfo
MG_EXPORT int GUIAPI GetTextWordInfo ( PLOGFONT  log_font,
const char *  mstr,
int  len,
int *  pos_words,
WORDINFO info_words 
)

Retrieves information of multi-byte words in a string.

This function retrieves information of multi-byte words in the string mstr which is len bytes long. It returns the positions of words in the string in an integer array pointed to by pos_words if the pointer is not NULL. This function also returns the information of words in a WORDINFO struct array pointed to by info_words when the pointer is not NULL.

Parameters
log_fontThe logical font used to parse the multi-byte string.
mstrThe multi-byte string.
lenThe length of the string.
pos_wordsThe position of words will be returned through this array if it is not NULL.
info_wordsThe words' information will be returned through this array if it is not NULL.
Returns
The number of words in the multi-byte string.
See also
GetTextMCharInfo, WORDINFO
MG_EXPORT int GUIAPI MB2WCEx ( PLOGFONT  log_font,
void *  dest,
BOOL  wc32,
const unsigned char *  mstr,
int  n 
)

Converts a multibyte character to a wide character in UCS according to the charset/encoding of the logical font.

Parameters
log_fontThe logical font.
destThe buffer used to store the wide character; can be NULL.
wc32Whether the wide char is 32-bit long. TRUE for yes, FALSE for 16-bit long.
mstrThe pointer to the multi-byte character.
nThe length of the multi-byte character.
Returns
If mchar is not NULL, the function returns the number of consumed bytes starting at mchar, or 0 if s points to a null byte, or -1 upon failure.
See also
WC2MBEx, mbtowc
MG_EXPORT int GUIAPI MBS2WCSEx ( PLOGFONT  log_font,
void *  dest,
BOOL  wc32,
const unsigned char *  mstr,
int  mstr_len,
int  n,
int *  conved_mstr_len 
)

Converts a multibyte string to a wide character string in UC16 according to the charset/encoding of the logical font.

This function is a MiniGUI version of ISO/ANSI mbstowcs function. It converts a multibyte string to a wide character string in UC16. The behaviour of mbstowcs depends on the LC_CTYPE category of the current locale, while MBS2WCS depends on the charset/encoding of MiniGUI logical font.

Parameters
log_fontThe logical font.
destThe buffer used to store the converted wide character string.
wc32Whether the unicode char is 32-bit long. TRUE for yes, FALSE for 16-bit long.
mstrThe pointer to multibyte string.
mstr_lenThe length of the multibyte string in bytes.
nThe length of the buffer in wide characters.
conved_mstr_lenThe length of the multibyte string which are converted correctly in bytes will be returned through this pointer, can be NULL.
Returns
The function returns the number of wide characters that make up the converted part of the wide character string, not including the terminating null wide character. If an invalid multibyte sequence was encountered, -1 is returned.
See also
WCS2MBSEx, mbstowcs, mbsrtowcs
MG_EXPORT int GUIAPI WC2MBEx ( PLOGFONT  log_font,
unsigned char *  s,
UChar32  wc 
)

Converts a wide character in UCS to a multibyte character according to the charset/encoding of the logical font.

Parameters
log_fontThe logical font.
sThe buffer used to store the converted multibyte characters.
wcThe wide character.
Returns
If s is not NULL, the function returns the number of bytes that have been written to the byte array at s. If wc can not be represented as a multibyte sequence (according to the current logfont), -1 is returned.
See also
WC2MB, mbtowc
MG_EXPORT int GUIAPI WCS2MBSEx ( PLOGFONT  log_font,
unsigned char *  dest,
const void *  wcs,
int  wcs_len,
BOOL  wc32,
int  n,
int *  conved_wcs_len 
)

Converts a wide character string in UC16 to a multibyte string according to the charset/encoding of the logical font.

This function is a MiniGUI version of ISO/ANSI wcstombs function. It converts a wide character string in UC16 to a multibyte string. The behaviour of wcstombs depends on the LC_CTYPE category of the current locale, while WCS2MBS depends on the charset/encoding of MiniGUI logical font.

Parameters
log_fontThe logical font.
destThe buffer used to store the converted multibyte string.
wcsThe pointer to the wide character string.
wcs_lenThe number of the wide characters in wcs.
wc32Whether the wide char is 32-bit long. TRUE for yes, FALSE for 16-bit long.
nThe length of the dest in bytes.
conved_wcs_lenThe number of the wide characters which are converted correctly will be returned through this pointer, can be NULL.
Returns
The function returns the number of bytes that make up the converted part of multibyte sequence, not including the terminating null byte. If a wide character was encountered which could not be converted, -1 is returned.
See also
MBS2WCSEx, wcstombs, wcsrtombs