acutPrintf

C++

ACDBCORE2D_PORT int acutPrintf(
    const ACHAR * format, 
    ...
);

File

acutads.h

Description

Displays a message on the AutoCAD text screen. This function is identical to the standard C library function printf(), except that acutPrintf() writes to the host application rather than the standard output stream stdout and also supports the ObjectARX/ObjectDBX-specific q conversion specifier. The q specifier allows conversion of doubles based on the current LUNITS/LUPREC, ALTUNIT/ALTPREC, or AUNITS/AUPREC system variables.

In addition, the order in which arguments appear in the formatted string can be different from the order in which the arguments are passed to the function. The sequence is specified using a number followed by the dollar sign. For example, "2$" indicates the second argument.

In other words, the following calls are both valid:

                acutPrintf("Error in file %s on line %d", filename, linenumber)
                acutPrintf("Error on line %2$d in file %1$s", filename, linenumber)

On success, acutPrintf() returns RTNORM; otherwise, it returns an error code.

Editing Codes

The conversion is qn where n is 0, 1, 2, 3, or *. In this context, n is the editing code. q0 edits a double-precision distance in accordance with the system variables LUNITS and LUPREC. LUPREC determines the editing precision. The meanings of the editing codes are as follows:

q1 edits a double-precision dimensionless number using ALTUNITS/ALTPREC rather than LUNITS/LUPREC for format control. Dimensionless means that no feet to inches conversion is performed; if ALTUNITS is 3 or 4, conversion occurs as though ALTUNITS is 5 (fractional).

q2 edits an angle, input in radians, in accordance with AUNITS/ AUPREC.

The angle is transformed into the user's angle space as specified by the variables ANGBASE and ANGDIR. The angle's sign is preserved, but the angle is reduced to the range (-360,360).

q3 is the same as q2, except that the angle is considered to be a relative angle. Surveyor's units are edited as degrees, minutes, and seconds, no ANGBASE and ANGDIR transformation is done, and the angle's value is not reduced.

q* allows the editing code (a short) to be specified as an argument to acutPrintf(). This allows the use of editing codes with the high byte as bit flags for more editing control. The AcUt::QFormatBitFlags enumerated type provides bit flags that can be set with specific base editing codes. The following matrix maps bit flags with valid base edit codes.

For example, the following code uses q* to format a relative angle (val) using ALTUNIT/ALTPREC and suppressing leading and trailing zeros if ALTUNIT is 0:

                    acutPrintf(buffer, "%.10q*", 3 & AcUt::kSuppressLeadingZero
                    & AcUt::kSuppressTrailingZero & AcUt::kUseAltUnits, val)
                  ;

Field Unit Specifiers

When you use a q operator, you must also use a field width specifier to ensure enough space for the formatted string. If the formatted string exceeds the field width, scientific notation is used regardless of the units format that is specified. The default width is 0, so you should specify some width value to avoid always ending up with scientific notation. The field width specifier .nn comes after the %, but before the q in the format string; for example: "%.10q2" The field width specifier specifies the maximum width. If the final formatted string is shorter than the specified field width, the string is not padded.

Note that for the q conversion operator, the .nn is used differently from the way it is used by other conversion operators, such as e or f, where .nn specifies the precision of the result.

For example, q0 uses the LUNITS and LUPREC system variables to determine the format. If LUNITS is 2 and LUPREC is 4, the format is decimal with 4 digits after the decimal point. For the number 5.66, acutPrintf() would output 5.6600, which is a total of 6 characters, so the field width specifier must be at least 6, as in the following example. Otherwise, the result will be in scientific notation.

                      double number = 5.66;

                      acutPrintf(buf, "%.6q0", number);

Parameters