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 listed above. |
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. |
This structure is used by the ImmGetCandidateList function.
When the dwStyle is IME_CAND_CODE, this candidate list structure has the special case. There are two cases: one is that dwCount is 1, and another is that 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 IME conversion engine. Using this, the IME can support the input like "A1?3". When the user input "A1?3", the IME provide 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