CANDIDATELIST

This structure is used by the ImmGetCandidateList function.

typedef struct tagCANDIDATELIST {
DWORD  dwSize;   // size of this data structure.
DWORD  dwStyle;  // style of candidate strings.
DWORD  dwCount;  // number of the candidate strings.
DWORD  dwSelection;  // index of a candidate string now selected.
DWORD  dwPageStart;  // index of the first candidate string in candidate 
                     //   window. It can vary with the page up or page 
                     //   down key.
DWORD  dwPageSize;   // preference number of candidate strings 
                     //   in one page.
DWORD  dwOffset[];   // startng positions of first candidate strings.
// Start positions of other (2nd, 3rd, ..) candidate strings are 
// appended after this field. IME can do this by reallocating the 
// hCandInfo memory handle, so IME can access dwOffset[2] (3rd candidate 
// string) or dwOffset[5] (6st candidate string). CHAR chCandidateStr[]; 
// the array of the candidate strings.
} CANDIDATELIST;
 

dwCandidateStyle

Can be a combination of these values:

Value	Meaning
IME_CAND_UNKNOWN	Candidates are in a style other style than that previously listed
IME_CAND_READ	Candidates are in same reading.
IME_CAND_CODE	Candidates are in a code range.
IME_CAND_MEANING	Candidates are in same meaning.
IME_CAND_RADICAL	Candidates use same radical character.
IME_CAND_STROKE	Candidates are in same number of strokes.

When the dwStyle is IME_CAND_CODE, this candidate list structure has the special case. There are two cases: one in which dwCount is 1, and the other in which dwCount is larger than 1.

When the dwCount equals 1:

dwSize is valid

dwStyle = IME_CAND_CODE

dwCount = 1

dwSelection = 0

dwPageStart = 0

dwPageSize is valid

dwOffset[0] is the offset of 'A140' (example code of a DBCS character)

At this time, the UI shows the candidate list, but the selected one is A140. For example, the UI may show the candidate list from A140 to A14F and the scroll bar at one page.

When the dwCount is larger than 1:

dwSize is valid

dwStyle = IME_CAND_CODE

dwCount is valid

dwSelection = index of dwOffset that is selected

dwPageStart = first index of dwOffset that is displayed

dwPageSize is valid

dwOffset[0] = offset of the first string

dwOffset[1] = offset of the second string

dwOffset[2] = offset of the third string

szCandStr[0] = "A140" string

szCandStr[1] = "A141" string

szCandStr[2] = "A142" string

At this time, the candidate list will be provided by the IME conversion engine. Using this, the IME can support the input like A1?3. When the user inputs A1?3, the IME provides the candidate list as follows.

dwCount = 0x10

dwSelection = index of dwOffset that is selected

dwPageStart = first index of dwOffset that is displayed

dwPageSize is valid

szCandStr[0x0] = "A103" string

szCandStr[0x1] = "A113" string

szCandStr[0x2] = "A123" string

.

.

.

szCandStr[0x0F] = "A1F3" string