GpiSetSegmentAttrs: Difference between revisions

Latest revision as of 15:41, 24 November 2025

This function sets a segment attribute.

Syntax

GpiSetSegmentAttrs(hps, lSegid, lAttribute, lValue)

Parameters

hps (HPS) - input

Presentation-space handle.

lSegid (LONG) - input

Segment identifier.

The identifier of the segment whose attribute is to be updated. It must be greater than zero.

lAttribute (LONG) - input

Segment attribute.

For details of the following attributes, see the GpiSetInitialSegmentAttrs function.

ATTR_DETECTABLE: Detectability

ATTR_VISIBLE: Visibility

ATTR_CHAINED: Chained

ATTR_DYNAMIC: Dynamic

ATTR_FASTCHAIN: Fast chaining

ATTR_PROP_DETECTABLE: Propagate detectability

ATTR_PROP_VISIBLE: Propagate visibility.

lValue (LONG) - input

Attribute value.

ATTR_ON: On/yes

ATTR_OFF: Off/no.

Return Value

rc (BOOL) - returns

Success indicator.

TRUE: Successful completion

FALSE: Error occurred.

Remarks

This function sets the value of one segment attribute for the specified segment. The segment can be any retained segment. If the identifier is that of the currently-open segment:

In retain mode, this is valid.
In draw-and-retain mode, the retained segment is updated, but there is no change to the immediate drawing.
In draw mode, it is invalid.

(For a description of drawing mode, see GpiSetDrawingMode). When a segment is modified from nonchained to chained, it is added to the end of the drawing chain.

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_SEG_ATTR (0x20C5): An invalid attribute parameter was specified with GpiSetSegmentAttrs, GpiQuerySegmentAttrs, GpiSetInitialSegmentAttrs, or GpiQueryInitialSegmentAttrs.
PMERR_INV_SEG_ATTR_VALUE (0x20C6): An invalid attribute value parameter was specified with GpiSetSegmentAttrs or GpiSetInitialSegmentAttrs.
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

This function is used to set the current value of the specified attribute.

#define INCL_GPISEGMENTS
#include <OS2.H>

HPS hps;  /*   Presentation-space */
          /*   handle.            */
LONG lSegid;   /* Segment identifier; must      */
               /* be greater than 0.            */
               /*                               */
               /* The name of the               */
               /* segment for which             */
               /* attribute information is to   */
               /* be returned.                  */
LONG lAttribute; /* attribute to be queried     */
LONG lValue;
lAttribute = ATTR_VISIBLE;


lValue = GpiSetSegmentAttrs(hps,
                            lSegid,
                            lAttribute,
                            ATTR_ON);

Related Functions