acedInitGet

C++

int acedInitGet(
    int val, 
    const ACHAR * kwl
);

File

acedads.h

Description

Initializes the options used by the next call to a user-input function, such as acedGetXxx(), acedDragGen(), acedEntSel(), acedNEntSelP(), or acedNEntSel().

Note The control bits and keywords established by acedInitGet() apply only to the next user-input function call. They are discarded immediately afterward. The application doesn't have to call acedInitGet() a second time to clear any special conditions.

If acedInitGet() succeeds, it returns RTNORM; otherwise, it returns RTERROR.

Input Options for User-Input Functions

The following table summarizes the control bits that can be specified by the val argument. To set more than one condition at a time, add the values together to create a val value between 0 and 255. If val is set to 0, none of the control conditions apply to the next user input function call.

Note Future versions of AutoCAD or ARX may use additional acedInitGet() control bits, so avoid setting bits that are not shown in the table.

The following list describes each of these control bits in more detail.

RSG_NONULL--Prevents the user from responding to the request by entering only [Return] or a space.

RSG_NOZERO--Prevents the user from responding to the request by entering 0.

RSG_NONEG--Prevents the user from responding to the request by entering a negative value.

RSG_NOLIM--Enables the user to enter a point outside the current drawing limits. This condition applies to the next user-input function even if the AutoCAD LIMCHECK system variable is currently set.

Not currently used.

RSG_DASH--Causes the rubber-band line or box that AutoCAD displays to be dashed instead of solid for those functions that let the user specify a point by selecting a location on the graphics screen. (Some display drivers use a distinctive color instead of dashed lines.) If the POPUPS system variable is 0, AutoCAD ignores this bit.

RSG_2D--Ignores the Z coordinate of three-dimensional points returned by acedGetDist(), so that an application can ensure that this function returns a two-dimensional distance.

RSG_OTHER--Allows arbitrary keyboard input. The function returns RTKWORD (acedDragGen() returns RTSTR in this case) and the application retrieves the value by calling acedGetInput(). (Because a space can terminate input for all user-input functions except acedGetString(), the arbitrary string ret- urned by acedGetInput() won't contain spaces.) This bit takes precedence over bit 0; if bit 7 is set and the user enters [Return] , a null string is returned.

RSG_DDISTFIRST--Give direct distance input precedence over arbitrary input. For external applications, arbitrary input is given precedence over direct distance input by default. Set this bit if you wish to force AutoCAD to evaluate user input as direct distance input. Note that legal point input from the keyboard always takes precedence over either direct distance or arbitrary input.

RSG_TRACKUCS--If RSG_TRACKUCS is set before a call to the acedGetPoint() or acedGetCorner() function, a temporary UCS will be established when the cursor crosses over the edge of a planar face of a solid. The temporary UCS is reset when the cursor moves off of a face. It is dynamically re-established when the cursor moves over a different face. After the point is acquired, the dynamic UCS is reset to the current UCS. This functionality is not enabled for non-planar faces such as the side of a cylinder.

RSG_NOORTHOZ--When calling the acedGetDist(), acedGetAngle(), acedGetOrient(), acedGetPoint(), or acedGetCorner() function, you may not want the distance, angle, orient, point, or corner to be influenced by ortho, polar, or otracking in the Z direction. Setting RSG_NOORTHOZ before calls to any of these functions will temporarily disable ortho, polar, and otracking in the Z direction. This is useful when you create 2D entities such as PLINE, ARC, or CIRCLE, or when you use the ARRAY command, which creates only a 2D array. In 2D-only commands it can be confusing and error-prone to allow 3D points to be entered using ortho Z, polar Z, or otrack Z.

Of course, certain control bits apply only to certain functions, depending on the type of value the user is requested to enter. If acedInitGet() sets a control bit and the application calls a user-input function for which the bit has no meaning, the bit is ignored. The following table shows which control bits apply to which user-input functions. (The control bit options don't apply to the acedGetString(), acedEntSel(), acedNEntSelP(), or acedNEntSel() functions.)

Keyword Specifications

The optional kwl argument specifies a list of keywords that will be recognized by the next user-input (acedGetXxx()) function call or by a call to acedDragGen(), acedEntSel(), acedNEntSelP(), or acedNEntSel(). The keyword value that the user enters can be retrieved by a subsequent call to acedGetInput(). (The keyword value will already be available if the user-input function was acedGetKword().) The meaning of the keywords and the action to perform for each is the responsibility of the ARX application.

The kwl argument is a single string, which is interpreted according to the following rules:

• Each keyword is separated from the next keyword by one or more spaces. For example, "Width Height Depth" defines three keywords.
• Each keyword can contain only letters, numbers, and hyphens (-).
• Each keyword specification can instruct AutoCAD to recognize abbreviations, according to one of two methods:
  • Enter the letters of the keyword that make up the required part (the abbreviation) in uppercase characters, and the remainder of the keyword in lowercase. For example, if you want the user to be able to type LT as an abbreviation of ltype, use the keyword "LType". The letters for the abbreviation don't need to be at the beginning of the keyword. For example, the user can select the keyword "eXit" by entering either exit or x.
  • Enter the entire keyword in uppercase characters, followed immediately by a comma, followed by the abbreviation. For example, enter LTYPE,LT.This method is useful in developing applications for languages that do not use uppercase and lowercase letters in the style of the Roman alphabet.

With either method, if the user enters LT (in either uppercase or lowercase letters), this is sufficient to identify the keyword. The user can enter characters that follow the required portion of the keyword, provided that they don't conflict with the specification. In the example, the user could also enter LTY or LTYP, but L would not be sufficient, and something like LTSCALE or LTYPEX would not match the spelling of the keyword.

• If kwl shows the keyword entirely in uppercase or lowercase characters, with no comma followed by an abbreviation, then AutoCAD recognizes only the keyword if the user enters all of it.

The acedGetInput() function always returns the keyword as it appears in the kwl argument with the same capitalization (but not with the optional characters, if those are specified after a comma). Regardless of how the user enters a keyword, the application has to do only one string comparison to identify it.

Globalization of Key Words

The kwl argument may be used for local and global language key word combinations. To associate local and global keywords, the kwl argument must consist of one or more local keywords, followed by an underscore, followed by the associated global keyword(s). In this example, Ja is paired with Yes and Nein is paired with with No:

acedInitGet(RSG_NONULL, "Ja Nein _ Yes No");

The keywords listed after the underscore are defined as global, and will always be the keywords returned.

The user can use local keywords by typing in the appropriate characters. Following the call made in the previous example, J would return Yes and and N would return No. To access a global keyword, the user must use a leading underscore followed by the appropriate characters. Again, following the call made in the previous example, _Y would return Yes and _N would return No. The leading underscore used in the function call does not become part of the keyword string returned.

A one-to-one match between local and global keywords is not required (that is, the function call will not fail if there is a mismatch), however:

• If there are more local keywords (before the underscore) than global (after the underscore), the local keywords without a corresponding global keyword will be accepted, but will return an empty string ("").
• If there are more global keywords (after the underscore) than local (before the underscore), the global keywords without a corresponding local keyword will be accepted (as long as the leading underscore is included) and returned.

The globalization mechanism works with both forms of keyword specification, as illustrated here:

acedInitGet(RSG_NONULL, "Ja NEIN,N _ YES,Y No");

This call is perfectly acceptable and will return YES or No.

Parameters