## Printer Device Driver

[prev][next][parent][TOC]

### GplStringSorterGetFirstString

Description

This function is used to get a linked list of strings from the string sorter in relation to a band rectangle passed in.

The strings are not deleted from the linked list on this call because we allocated the information and will de-allocate on a GplStringSorterReset() call or a GplStringSorterRemoveStrings() call.

Currently, the defined relationships that can be selected are:

Option Description

STR_INCL_PART_IN_BAND Return any string whose text box intersects any part of the band passed in.

STR_INCL_ALL_IN_BAND Return any string whose text box is entirely inside the band passed in.

STR_INCL_TOPLEFT_IN_BAND Return any string whose top-left coordinate is inside the band passed in.

Notes:

1.All retrievals are inclusive on all boundaries of the rectlBand passed in.

2.GplStringSorterGetFirstString retrievals are non-destructive. (the string remains in the string-sorter instance and are only removed by GplStringSorterRemoveStrings or GplStringSorterReset calls).

Format

    APIRET APIENTRY GplStringSorterGetFirstString( HSORTER  hStrSort,

                                                   ULONG    ulOption,

                                                   RECTL    rectlBand,

                                                   PSZ      *ppszStr,

                                                   PRECTL   prectlStr,

                                                   PPVOID   ppUserDef );

Parameters

hStrSort (HSORTER) Handle of string-sorter instance to be used for string retrieval.

ulOption (ULONG) Option passed in to indicate the relationship to test for on the "Get" operation. See options above.

rectlBand (RECTL) The band rectangle passed in that will be used to test all text-string rectangles against.

*ppszStr (PSZ)-output Pointer to first text string meeting retrieve criteria (ulOption).

prectlStr (PRECTL)-output Pointer to the bounding rectangle of first string retrieved (passed in during GplStringSorterInsertString).

ppUserDef (PPVOID)-output Pointer to the user-defined data that was associated with text string retrieved (passed in during GplStringSorterInsertString).

Returns

Success NO_ERROR
Failure ERROR_xxx