acedTablet

C++

int acedTablet(
    const struct resbuf * args, 
    struct resbuf ** result
);

File

acedads.h

Description

Depending on the first item in args, either retrieves the current digitizer (tablet) calibration or sets the calibration. The first item in args must be an integer (RTSHORT) whose value is either 0 or 1. If args begins with 0, acedTablet() retrieves the current calibration and returns it in the result list. If args begins with 1, it must also specify the new calibration arguments. The elements of args and result have the same meanings, as follows:

codeAn integer code (RTSHORT).

If the code you pass in args equals 0, acedTablet() retrieves the current calibration in result; in this case you must not provide the other arguments. If the code you pass in args equals 1, acedTablet() sets the calibration according to the arguments that follow; in this case you must provide the other arguments.

The code returned in result always equals 1.row1, row2, row3Three three-dimensional points (RT3DPOINT). These arguments specify the three rows of the tablet's transformation matrix.directionA three-dimensional point (RT3DPOINT). This is the vector (expressed in the World Coordinate System, or WCS) that is normal to the plane that represents the surface of the tablet. When you retrieve a tablet calibration (the code in args equals 0), you should declare result as a **resbuf. The acedTablet() function allocates the items in the result list. You should release it later with a call to acutRelRb().

When you set a tablet calibration (the code in args equals 1), you can pass the result argument as NULL. This tells acedTablet() to set the calibration "silently," without returning the new calibration values. If you set the calibration but pass result as a declared resbuf pointer, acedTablet() sets result to the new calibration. The values returned in result should equal the values specified in args, with the following possible exceptions:

• If the direction specified in args isn't normalized, acedTablet() corrects it, so the direction it returns when you set the calibration may differ from the value you passed.
• In a similar way, the third element in row3 (row3[Z]) should always equal 1. The acedTablet() function returns it as 1 even if the row3 in args specified a different value.

When you call acedSetVar() to set the tablet mode, make sure that the call was successful--even if it returned RTNORM--by using acedGetVar() to get the value of the TABMODE system variable and by checking that TABMODE is no longer 0.

If acedTablet() succeeds, it returns RTNORM; otherwise, it returns an error code. If acedTablet() fails, it sets the system variable ERRNO to a value that indicates the reason for the failure.

Parameters

Returns

Pointer to a result buffer containing the resulting tablet calibration