GpiQuerySegmentPriority

This function returns the identifier of the named segment that is chained immediately before or after a specified reference segment.

Syntax

GpiQuerySegmentPriority(hps, lRefSegid, lOrder)

Parameters

hps (HPS) - input: Presentation-space handle.

lRefSegid (LONG) - input: Reference-segment identifier.

lOrder (LONG) - input

Segment higher or lower.

Shows whether a segment identifier of a higher or lower priority than identified in the lRefSegid parameter is to be returned. Possible values are:

LOWER_PRI: Return the next segment with a lower priority than lRefSegid. If lRefSegid =0, query the identifier of the segment with the lowest priority.
HIGHER_PRI: Return the next segment with a higher priority than lRefSegid. If lRefSegid =0, query the identifier of the segment with the highest priority.

Return Value

lSegid (LONG) - returns

Segment identifier.

The identifier of the segment that is immediately before or after that specified in the lRefSegid parameter:

>0: Segment identifier.
0: The segment specified in the lRefSegid parameter is either the lowest-priority segment (when lOrder = LOWER_PRI) or the highest-priority segment (when lOrder = HIGHER_PRI).
GPI_ALTERROR: Error.

Remarks

The segment that is chained before the specified segment, is considered to have a lower priority than the specified segment; similarly, the segment that is chained after the specified segment, is considered to have a higher priority than the specified segment. Unnamed segments (with an identifier of zero) are ignored.

Errors

Possible returns from WinGetLastError:

PMERR_INV_HPS (0x207F): An invalid presentation-space handle was specified.
PMERR_PS_BUSY (0x20F4): An attempt was made to access the presentation space from more than one thread simultaneously.
PMERR_INV_SEG_NAME (0x20C8): An invalid segment identifier was specified.
PMERR_INV_ORDERING_PARM (0x20AB): An invalid order parameter was specified with GpiSetSegmentPriority.
PMERR_SEG_NOT_CHAINED (0x20FF): An attempt was made to issue GpiDrawFrom, GpiCorrelateFrom or GpiQuerySegmentPriority for a segment that was not chained.
PMERR_SEG_NOT_FOUND (0x2100): The specified segment identifier did not exist.
PMERR_INV_MICROPS_FUNCTION (0x20A1): An attempt was made to issue a function that is invalid in a micro presentation space.

Example Code

#define INCL_GPISEGMENTS /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS  hps;       /* Presentation-space handle. */
LONG lRefSegid; /* Reference-segment identifier. */
LONG lOrder;    /* Segment higher or lower. */
LONG lSegid;    /* Segment identifier. */

lSegid = GpiQuerySegmentPriority(hps, lRefSegid, lOrder);

This function returns the identifier of the named segment that is chained immediately before or after a specified reference segment.

#define INCL_GPISEGMENTS
#include <OS2.H>

HPS hps; /* Presentation-space */
/* handle. */
LONG lSegid; /* Segment identifier */
LONG lRefSegid; /* Reference-segment */
/* identifier. */
LONG lOrder; /* Shows whether a */
/* segment identifier of a */
/* higher or lower priority */
/* than identified in the */
/* lRefSegid parameter is */
/* to be returned. */

lOrder = HIGHER_PRI; /* Return the next */
/* segment with a higher */
/* priority than */
/* lRefSegid. If */
/* lRefSegid=0, query */
/* the identifier of the */
/* segment with the */
/* highest priority. */

lRefSegid = 0; /* find the segment with the highest */
/* priority. */

lSegid = GpiQuerySegmentPriority(hps,
    lRefSegid,
    lOrder);

Related Functions

GpiSetSegmentPriority