Jump to content

GpiSetSegmentPriority

From EDM2
Revision as of 23:03, 6 April 2025 by Iturbide (talk | contribs) (Created page with "This function changes the position of a segment within the segment chain, or adds a segment to the chain. ==Syntax== GpiSetSegmentPriority(hps, lSegid, lRefSegid, lOrder) ==Parameters== ; hps (HPS) - input : Presentation-space handle. ; lSegid (LONG) - input : Segment identifier. : The identifier of the segment whose priority is to be changed; it must be greater than 0. ; lRefSegid (LONG) - input : Reference segment identifier. : The segment that identif...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

This function changes the position of a segment within the segment chain, or adds a segment to the chain.

Syntax

GpiSetSegmentPriority(hps, lSegid, lRefSegid, lOrder)

Parameters

hps (HPS) - input
Presentation-space handle.
lSegid (LONG) - input
Segment identifier.
The identifier of the segment whose priority is to be changed; it must be greater than 0.
lRefSegid (LONG) - input
Reference segment identifier.
The segment that identifies a position in the segment chain. The segment specified in the lSegid parameter is placed either immediately before or after this segment, depending on the value specified in the lOrder parameter. Specifying 0 for lRefSegid indicates that the position is to be the beginning or the end of the segment chain as defined by the value in the lOrder parameter.
lOrder (LONG) - input
Segment higher or lower.
Specifies whether the segment named in the lSegid parameter is to be placed before or after the segment named in the lRefSegid parameter. Possible values are:
LOWER_PRI
The segment named in the lSegid parameter is to have a lower priority than the segment named in the lRefSegid parameter. The lSegid segment is placed before the lRefSegid segment. If 0 is specified in the lRefSegid parameter, the segment identified in the lSegid parameter is placed as the highest priority segment.
HIGHER_PRI
The segment named in the lSegid parameter is to have a higher priority than the segment named in the lRefSegid parameter. The lSegid segment is placed after the lRefSegid segment. If 0 is specified in the lRefSegid parameter, the segment identified in the lSegid parameter is placed as the lowest priority segment.

Return Value

rc (BOOL) - returns
Success indicator.
TRUE
Successful completion
FALSE
Error occurred.

Remarks

The specified segment can be a segment that exists in the segment chain, or an unchained segment. The effect of this function on an unchained segment is to add it to the segment chain in the specified position. The application may redraw the picture by drawing the segment chain (see GpiDrawChain). This causes the segments in the chain to be processed from beginning to end, so that if segments overlap, later ones are placed on top of earlier ones (assuming a default mix mode) and therefore appear to have higher priority. Changing the position of the segment in the chain therefore has the effect of changing its priority to the end user.

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_AND_REFSEG_ARE_SAME (0x20FA)
The segid and refsegid specified with GpiSetSegmentPriority were the same.
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 lSegid;    /* Segment identifier. */
LONG lRefSegid; /* Reference segment identifier. */
LONG lOrder;    /* Segment higher or lower. */
BOOL rc;        /* Success indicator. */

rc = GpiSetSegmentPriority(hps, lSegid, lRefSegid, lOrder);

This example finds the segment with the highest priority and places a segment just before it with a lower priority.

#define INCL_GPISEGMENTS
#include <OS2.H>

HPS hps; /* Presentation-space */
/* handle. */
LONG lRefSegid; /* Reference-segment */
/* identifier. */
LONG laddSegid = 20L;
LONG lSegid;

lSegid = GpiQuerySegmentPriority (hps,
    /* find the segment with the highest */
    /* priority. */
    0,
    HIGHER_PRI);

GpiSetSegmentPriority(hps,
    lRefSegid,
    laddSegid,
    LOWER_PRI);

Related Functions