GpiSetInitialSegmentAttrs
This function specifies a segment attribute that is used when a segment is subsequently created.
Syntax
GpiSetInitialSegmentAttrs(hps, lAttribute, lValue)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- lAttribute (LONG) - input
- Segment attribute.
- The following values can be ORed together to generate this parameter:
- ATTR_DETECTABLE
- Detectability.
- This can be used to determine whether a correlation function can be performed on the primitives within the segment. For correlation on retained segments see:
- * GpiCorrelateChain
- * GpiCorrelateFrom
- * GpiCorrelateSegment.
- Correlation on primitives outside segments is controlled by the correlate flag on draw controls (see GpiSetDrawControl).
- ATTR_VISIBLE
- Visibility.
- Controls whether a segment is to be made visible on the output medium.
- ATTR_CHAINED
- Chained.
- Controls whether the segment is a root segment to be included in the segment drawing chain. In draw or draw-and-retain modes (see GpiSetDrawingMode) a chained segment is drawn as it passes across the API; an unchained segment is not.
- Unchained segments are usually called from another segment. They can also be segments that are inserted into the chain later (with GpiSetSegmentPriority or GpiSetSegmentAttrs), or segments that are drawn individually with GpiDrawSegment.
- ATTR_DYNAMIC
- Dynamic.
- Controls whether the segment is to be dynamic; that is, drawn using exclusive-OR, so that it can be readily erased by redrawing it. (See GpiDrawDynamics, GpiRemoveDynamics, and the DCTL_DYNAMIC option of GpiSetDrawControl.)
- Only retained segments can be dynamic.
- The dynamic segment attribute is always ignored if the segment is not currently chained.
- ATTR_FASTCHAIN
- Fast chaining.
- Controls whether, for a chained segment, the system can assume that all primitive attributes need not be reset to default values before execution of the segment.
- ATTR_PROP_DETECTABLE
- Propagate detectability.
- Controls whether the value of the detectability attribute for a segment should be propagated (forced) to all segments beneath it in the hierarchy.
- ATTR_PROP_VISIBLE
- Propagate visibility.
- Controls whether the value of the visibility attribute for a segment should be propagated (forced) to all segments beneath it in the hierarchy.
- 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
Initial segment attributes are modal settings used to determine the initial attributes of new segments as they are created; that is, when an GpiOpenSegment function is issued, and the segment does not already exist. The default values of initial segment attributes are:
- Not detectable
- Visible
- Chained
- Not dynamic
- Fast chaining
- Propagate detectability
- Propagate visibility.
A nonretained segment can never be given the dynamic attribute. Primitives outside segments are not affected by GpiSetInitialSegmentAttrs.
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_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_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 lAttribute; /* Segment attribute. */ LONG lValue; /* Attribute value. */ BOOL rc; /* Success indicator. */ rc = GpiSetInitialSegmentAttrs(hps, lAttribute, lValue);
This function specifies a segment attribute that is used when a segment is subsequently created. In this example, the most common attributes are selected.
#define INCL_GPISEGMENTS
#include <OS2.H>
HPS hps; /* Presentation-space */
/* handle. */
GpiSetInitialSegmentAttrs (hps,
ATTR_DETECTABLE |
ATTR_VISIBLE |
ATTR_DYNAMIC |
ATTR_PROP_DETECTABLE |
ATTR_PROP_VISIBLE,
ATTR_ON);