| MIL 10 Reference
| Customize Help
| Save Settings

MstrEditFont


See also
Availability
Not available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
MstrDraw
MstrExpert
Synopsis
Edit a specified font.
Syntax
void MstrEditFont(
MIL_ID ContextId, //in
MIL_INT FontIndex, //in
MIL_INT64 Operation, //in
MIL_INT64 OperationMode, //in
MIL_INT Param1, //in
const void *Param2Ptr, //in
const void *Param3Ptr //in
)
Description

This function allows you to edit a specified font. For example, you can add or remove characters from a font, as well as normalize a character in a font. Use MstrControl() with M_FONT_ADD to add a font to the context.

Note that this function is only available for a font-based context.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.
Parameters
This function is not supported on the selected boards.
Parameters
ContextId

Specifies the String Reader context that contains the font to edit. The String Reader context must have been previously allocated on the required system using MstrAlloc().

FontIndex

Specifies the index of the font to edit.

function map For specifying the font to edit
CollapseValue Description
Collapse

Specifies the font to which to apply the edit settings.

(summarize)
Parameters

This parameter specifies the index of the font to edit. You can set this parameter to the following:
Value >= 0

Specifies the index of the individual font.
Operation

Specifies the operation to be performed.

See the Parameter associations section for possible values that can be specified.

OperationMode

Specifies the mode of the operation.

See the Parameter associations section for possible values that can be specified.

Param1

Specifies a value that is dependent on the operation and mode chosen.

Set this parameter to M_DEFAULT if not used.

See the Parameter associations section for possible values that can be specified.

Param2Ptr

Specifies the address of the value that will be used to edit the font. The value is dependent on the operation and mode chosen.

See the Parameter associations section for possible values that can be specified.

Param3Ptr

Specifies the address of the value that will be used to edit the font. The value is dependent on the operation and mode chosen.

Set this parameter to M_NULL if not used.

See the Parameter associations section for possible values that can be specified.

Parameter associations

The table below lists possible values for the Operation, OperationMode, Param1, Param2Ptr, and Param3Ptr parameters.

To specify the operation to perform, set the Operation, OperationMode, Param1, Param2Ptr, and Param3Ptr parameters to the following values:

function map For performing the operation
CollapseOperation Description
OperationMode
Param1
Param2Ptr
Param3Ptr
Collapse M_CHAR_ADD

Adds a character to the font.

(summarize)
Collapse M_SYSTEM_FONT +

Specifies that characters from a given system font (for example, TrueType and Postscript) will be added.

(summarize)
Collapse Param1

Specifies the size of the characters to add. INQ

(summarize)
Collapse Value > 6

Specifies the size, in points.
Collapse Param2Ptr
Data type info

Specifies an optional string containing all of the characters to add.

Two characters in one font cannot have the same value. If you try to add a character with a value that already exists in a font, the existing character will be replaced by the newly added one, unless you use M_NO_OVERWRITE. For more information, see the combination constants tables below.

(summarize)
Collapse M_NULL

Specifies that the standard characters of the font will be added. That is, A to Z, a to z, and 0 to 9.

(summarize)
Collapse "String"

Specifies the string. This must be a null-terminated string.

(summarize)
Collapse Param3Ptr
Data type info

Data type: MIL_CONST_TEXT_PTR

Specifies the following.

(summarize)
Collapse MIL_TEXT("System font file name") 1

Specifies the string containing the font's file name (for example, "TrueType" and "Postscript"). This must be a null-terminated string.

(summarize)
Collapse M_USER_DEFINED +

Specifies that user-defined characters will be added from a given image to the specified font.

(summarize)
Collapse Param1

Specifies the identifier of the image containing the characters to add.

(summarize)
Collapse Image identifier

Specifies the image idenfitier. The characters to add in the image must all be approximately the same size. You cannot add a character that is smaller than 6x6 pixels. Note that the size of the characters is automatically determined from the image.

The characters in the image are taken from left to right and from top to bottom and are associated with the corresponding characters given in the character list. Each character in the image must be entirely connected (except for the accentuated characters) and should not be merged with other characters or other image objects.

It is best to provide a character definition image that is of good quality, and that ideally contains only the characters that you want to add to the font (though this is not mandatory). If all the characters in the string you want to add cannot be found in the image, an error is returned. Even if the operation succeeds, you should draw the characters of the font to ensure that every character is defined as expected, using MstrDraw().

The image must be of type 1-band, 8-bit, unsigned. This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

(summarize)
Collapse Param2Ptr
Data type info

Specifies a string containing all of the characters to add. Unlike M_SYSTEM_FONT, this setting is not optional.

(summarize)
Collapse "String"

Specifies the string. This must be a null-terminated string.

Two characters in one font cannot have the same value. If you try to add a character with a value that already exists in a font, the existing character will be replaced by the newly added one, unless you use M_NO_OVERWRITE. For more information, see the combination constants tables below.

For a multi-string definition image, the space character (ASCII 32) must be inserted to separate the strings included in this null-terminated string.

You should use multi-strings when one (or more) of the following situations is encountered: the characters are not all on the same line, the contrast is clearly different between characters, there is clearly a horizontal space between the characters (for example, ABC DEF).

(summarize)
Collapse Param3Ptr

This parameter must be set to M_NULL.
Collapse M_USER_DEFINED + M_SINGLE +

Specifies that a single user-defined character will be added from a given image in the specified font.

If you use M_USER_DEFINED + M_SINGLE, the whole image is taken as a single character. This allows you to define special characters, which are not necessarily connected. The image is associated with the character specified by the Param2Ptr parameter.

It is best to provide a character definition image that is of good quality. Note that if the character you want to add already exists in the font, the new character will replace the old one. You cannot add a character that is smaller than 6x6 pixels. By default, user-defined characters have no baseline.

(summarize)
Collapse Param1

Specifies the identifier of the image containing the characters to add.

(summarize)
Collapse Param2Ptr
Data type info

Specifies the pointer of the character to add.
Collapse Param3Ptr

This parameter must be set to M_NULL.
Collapse M_CHAR_BASELINE

Sets the baseline of the characters in the font. INQ

(summarize)
Collapse M_DEFAULT

Implements the default behavior.

By default, for system fonts (M_SYSTEM_FONT), the baseline will be taken from that font's file.

By default, for user-defined fonts (M_USER_DEFINED), the baseline will be set to M_AUTO_COMPUTE, which automatically computes the baseline to an appropriate value.

When using a font to read a string model, the baseline of all characters in the string model are expected to be aligned together within a certain degree of tolerance (set using MstrControl() with M_CHAR_MAX_BASELINE_DEVIATION), otherwise the string will not be read.

(summarize)
Collapse Param1

Specifies the baseline.

(summarize)
Collapse M_AUTO_COMPUTE

Specifies that the baseline will be automatically computed to an appropriate value.
Collapse M_NONE

Specifies no baseline.
Collapse -1000 <= Value <= 1000

Specifies the baseline value, as a percentage of the character's height.

The position of the baseline in a character is defined as a percentage of the height of the character. That is, 0 refers to the bottom of character, 100 refers to the top of the character, and 50 refers to the middle of character. For example, in "ABCD", you would typically set the baseline to 0 for all characters, while in "pobq", you would typically set the baseline to 0 for "ob" and approximately 25 for "pq". Note that you can set a baseline value that falls outside the limits of the character's height (Y-size).

(summarize)
Collapse Param2Ptr
Data type info

Specifies an optional string containing all the characters for which you want to set a baseline.

(summarize)
Collapse M_NULL

Specifies that the baseline will be set for all the characters in the font.
Collapse "String"

Specifies the string. This must be a null-terminated string.

(summarize)
Collapse Param3Ptr

This parameter must be set to M_NULL.
Collapse M_CHAR_DELETE

Deletes characters from the font.

(summarize)
Collapse M_DEFAULT

Implements the default behavior.

(summarize)
Collapse Param1

This parameter must be set to M_DEFAULT.
Collapse Param2Ptr
Data type info

Specifies an optional string containing all the characters to delete.

(summarize)
Collapse M_NULL

Specifies to delete all the characters in the font.
Collapse "String"

Specifies the string of characters to delete. This must be a null-terminated string.

(summarize)
Collapse Param3Ptr

This parameter must be set to M_NULL.
Collapse M_CHAR_NORMALIZE

Normalizes the characters of the font.

(summarize)
Collapse M_SIZE_X

Specifies that the characters of the font are normalized by taking the X-size as the reference. That is, all the specified characters will be uniformly scaled to a given X-size. Note that the characters' Y-size is adjusted to maintain the same aspect ratio.

(summarize)
Collapse Param1

Specifies the X-size. INQ

(summarize)
Collapse Value >= 8

Specifies the size, in pixels.
Collapse Param2Ptr
Data type info

Specifies an optional string containing all the characters to normalize.

(summarize)
Collapse M_NULL

Specifies that all the characters in the font will be normalized a given X-size.
Collapse "String"

Specifies the string. This must be a null-terminated string.

(summarize)
Collapse Param3Ptr

This parameter must be set to M_NULL.
Collapse M_SIZE_Y

Specifies that the characters of the font are normalized by taking the Y-size as the reference. That is, all the specified characters will be uniformly scaled to a given Y-size. Note that the characters' X-size is adjusted to maintain the same aspect ratio.

(summarize)
Collapse Param1

Specifies the Y-size. INQ

(summarize)
Collapse Value >= 8

Specifies the size, in pixels.
Collapse Param2Ptr
Data type info

Specifies an optional string containing all the characters to normalize.

(summarize)
Collapse M_NULL

Specifies that all the characters in the font will be normalized a given Y-size.
Collapse "String"

Specifies the string. This must be a null-terminated string.

(summarize)
Collapse Param3Ptr

This parameter must be set to M_NULL.
Collapse M_CHAR_SORT

Sorts the characters of the font.

(summarize)
Collapse M_ASCENDING

Specifies that the characters will be sorted, according to their character values, in ascending order.

(summarize)
Collapse Param1

This parameter must be set to M_DEFAULT.
Collapse Param2Ptr
Data type info

Specifies an optional string containing all the characters to sort.

(summarize)
Collapse M_NULL

Specifies that all the characters in the font will be sorted in ascending order.
Collapse "String"

Specifies the string. This must be a null-terminated string.

(summarize)
Collapse Param3Ptr

This parameter must be set to M_NULL.
Collapse M_DESCENDING

Specifies that the characters will be sorted, according to their character values, in descending order.

(summarize)
Collapse Param1

This parameter must be set to M_DEFAULT.
Collapse Param2Ptr
Data type info

Specifies an optional string containing all the characters to sort.

(summarize)
Collapse M_NULL

Specifies that all the characters in the font will be sorted in descending order.
Collapse "String"

Specifies the string. This must be a null-terminated string.

(summarize)
Collapse Param3Ptr

This parameter must be set to M_NULL.
Collapse M_CHAR_TYPE

Sets the type of the characters in the font.

(summarize)
Collapse M_DEFAULT

Implements the default behavior.

(summarize)
Collapse Param1

Specifies the characters' type. INQ

(summarize)
Collapse M_AUTO_COMPUTE

Specifies that the characters' type will be computed automatically. The type will be set to either M_REGULAR or M_PUNCTUATION, based on the character's shape and numerical code.

(summarize)
Collapse M_PUNCTUATION

Specifies punctuation type characters. Punctuation characters can typically be categorized as characters that are neither letters nor numbers, such as the hyphen ('-'). Note that to be considered part of the string, a punctuation character must fall within the range of at least one regular character's Y-size.

(summarize)
Collapse M_REGULAR

Specifies regular type characters. Regular characters can typically be categorized as letters and numbers. Note that a string is formed by a linear sequence of regular characters.

(summarize)
Collapse Param2Ptr
Data type info

Specifies an optional string containing all the characters for which to set the type.

(summarize)
Collapse M_NULL

Specifies that the type will be set for all the characters in the font.
Collapse "String"

Specifies the string. This must be a null-terminated string.

(summarize)
Collapse Param3Ptr

This parameter must be set to M_NULL.
Collapse M_THICKEN_CHAR

Thickens the characters of the font. The characters of the font should always be the thickened version, so use this Operation if the font has dotted characters. INQ

(summarize)
Collapse M_DEFAULT

Implements the default behavior.

(summarize)
Collapse Param1

Specifies the number of character thickening iterations.

Each iteration enlarges the thickness of the target character of the font. This is useful for some types of fonts (for example, dotted characters). You should choose a value large enough for the intra character dots to connect.

(summarize)
Collapse 0 <= Value <= 100

Specifies the number of iterations.
Collapse Param2Ptr
Data type info

Specifies an optional string containing all the characters to normalize.

(summarize)
Collapse M_NULL

Specifies to normalize all the characters of the font.
Collapse "String"

Specifies the string. This must be a null-terminated string.

(summarize)
Collapse Param3Ptr

This parameter must be set to M_NULL.

1 If you are passing the value in a variable, don't enclose it in MIL_TEXT().

Combination constants for M_USER_DEFINED (when Operation=M_CHAR_ADD); M_USER_DEFINED + M_SINGLE (when Operation=M_CHAR_ADD).

You can add one of the following values to the above-mentioned values to set the foreground of the characters in the definition image when adding user-defined characters to a font.

Note that when a font is defined, it has no foreground. When performing a read operation (MstrRead()), the foreground the font is read with is set using M_FOREGROUND_VALUE in MstrControl(). In this case (when adding user-defined characters to a font), you are setting the foreground for the font in the definition image.

function map For setting the foreground of the characters
CollapseCombination value Description
Collapse M_FOREGROUND_BLACK

Specifies that black is the foreground color, for the definition image.

This is the default value.

(summarize)
Collapse M_FOREGROUND_WHITE

Specifies that white is the foreground color, for the definition image.
Combination constant for M_SYSTEM_FONT (when Operation=M_CHAR_ADD); M_USER_DEFINED (when Operation=M_CHAR_ADD); M_USER_DEFINED + M_SINGLE (when Operation=M_CHAR_ADD).

You can add the following value to the above-mentioned values to specify that characters will not be added to the font if they already exist.

function map For not overwriting characters
CollapseCombination value Description
Collapse M_NO_OVERWRITE

Specifies that the characters previously added to the font will not be overwritten.

This is the default value.

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib; milstr.lib.
DLL Requires mil.dll; milstr.dll.
CHAR ADD SYSTEM FONT NULL USER DEFINED UNSIGNED PROC NONE USER DEFINED M SINGLE PROC CHAR BASELINE DEFAULT AUTO COMPUTE NONE NULL CHAR DELETE DEFAULT NULL CHAR NORMALIZE SIZE X NULL SIZE Y NULL CHAR SORT ASCENDING NULL DESCENDING NULL CHAR TYPE DEFAULT AUTO COMPUTE PUNCTUATION REGULAR NULL THICKEN CHAR DEFAULT NULL FOREGROUND BLACK FOREGROUND WHITE NO OVERWRITE ASCII UNICODE