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);