User Breaks

The user-input functions and the acedCommandS()/acedCommandC(), acedCmdS()/acedCmdC(), acedEntSel(), acedNEntSelP(), acedNEntSel(), acedDragGen(), and acedSSGet() functions return RTCAN if the AutoCAD user responds by pressing ESC. An external function should treat this response as a cancel request and return immediately. ObjectARX also provides a function, acedUsrBrk(), that explicitly checks whether the user pressed ESC. This function enables ObjectARX applications to check for a user interrupt.

An application doesn't need to call acedUsrBrk() unless it performs lengthy computation between interactions with the user. The function acedUsrBrk() should never be used as a substitute for checking the value returned by user-input functions that can return RTCAN.

In some cases, an application will want to ignore the user's cancellation request. If this is the case, it should call acedUsrBrk() to clear the request; otherwise, the ESC will still be outstanding and will cause the next user-input call to fail. (If an application ignores the ESC, it should print a message to tell the user it is doing so.) Whenever an ObjectARX application is invoked, the ESC condition is automatically cleared.

For example, the following code fragment fails if the user enters ESC at the prompt.

int test() 
{ 
    int i; 
    while (!acedUsrBrk()) { 
        acedGetInt("\nInput integer:", &i); // WRONG
        . 
        . 
        . 
    } 
}

The slightly modified code fragment that follows correctly handles an input of ESC without calling acedUsrBrk().

int test() 
{ 
    int i; 
    for (;;) { 
        if (acedGetInt("\nInput integer:", &i) != RTNORM) 
            break; 
        ... 
    } 
}

The following sample changes the loop condition. This construction also works correctly.

int test()
{
    int i;
    while (acedGetInt("\nInput integer:", &i) == RTNORM) {
        ...
    }
}

A valid place to use acedUsrBrk() is in a lengthy operation. For example, code that steps through every entity in the drawing database can be time consuming and should call acedUsrBrk().