Generic presentation parameters Foundation

This section lists the presentation parameters that can be defined or altered for all Xbase Parts derived from the XbpWindow() class. They define the visual attributes of an Xbase Part when the :new(), :create()or :configure() methods are called (life cycle methods). If specified, the presentation parameters are defined as a 2-column array.

The presentatiopn parameter array is the fifth parameter of the beforementioned life cycle methods. The example below defines the foreground color and a font for a single line entry field:

aPP := { { XBP_PP_FGCLR       , GRA_CLR_RED         }, ; 
         { XBP_PP_COMPOUNDNAME, FONT_DEFFIXED_SMALL }  } 

oXbp := XbpSle():new( ,, { 100, 150 }, { 160, 25 }, aPP ) 
oXbp:create() 

It is strongly recommended to use the presentation parameter array when the appearance of an Xbase Part should differ from what is defined in the system control panel. Although individual presentation parameters can be set by calling the equivalent methods of an Xbase Part, the array is the fastest way to define the visual appearance upon creation of an Xbase Part, since multiple attributes can be set within one method call. To set multiple presentation parameters after an Xbase Part is created results in less efficient code execution. The methods listed in the third column of the table above are provided to temporarily change a single presentation parameter in a convenient way. These methods should not be called immediately after an Xbase Part is created. For example, the result of the code above could also be achieved in this way:

oXbp := XbpSle():new( ,, { 100, 150 }, { 160, 25 } ) 
oXbp:create() 
oXbp:setColorFG( GRA_CLR_RED ) 
oXbp:setFontCompoundName( FONT_DEFFIXED_SMALL ) 

This code is not recommended. It is much less efficient than passing a presentation parameter array to the :new()method. When multiple presentation parameters are to be changed after the Xbase Part is created, the :setPresParam() method is the appropriate way. It accepts a presentation parameter array.

All presentation parameters of Xbase Parts have the initial value NIL, so that the appearance of the GUI controls conforms to the settings selected in the system control panel. An exception is the background color, which can be selected indepently for certain elements under Windows. The table below lists the system color constants set as the background color for various Xbase Parts.

Values for presentation parameters

All presentation parameters that are not specified when an Xbase Part is created are set to the respective system setting defined in Control Panel. An exception to this rule is when the respective presentation parameter is specified for the parent object. This is called "presentation parameter inheritance". Through inheritance, it is possible to define the font of a dialog window once, so that all Xbase Parts displayed in the dialog window inherit the font setting of the dialog window they are embedded in, for example.

The left column of the presentation parameter array contains always #define constants that identify a particular presentation parameter. The right column of that array holds the value the presentation parameter is to be set to. In most cases, valid values for presentation parameters are also #define constants. The constants are #define'd either in the #include file XBP.CH or GRA.CH.

XBP_PP_BGCLR and XBP_PP_FGCLR

The #define constants to specify the color of an Xbase Part are prefixed either with XBPSYSCLR_* (color defined in the system control panel) or with GRA_CLR_* (VGA palette color). When an XBPSYSCLR_* constant is used as value for a color, an Xbase Part changes its color during runtime when that particular color attribute is changed to a new value in the system control panel. An exception to this rule is the special color XBPSYSCLR_TRANSPARENT which can be used together with XBP_PP_BGCLRto have an Xbase Part render its background in a way that leaves certain areas transparent. Not all Xbase Parts support this feature.

If a GRA_CLR_* #define constant is specified as value of a color, an Xbase Part does not react to changes made in the system control panel while an Xbase++ program is running.

Instead of using #define constants, a RGB color value can be used to specify the color of an Xbase Part. RGB color values are calculated by the function GraMakeRGBColor() which calculates a color from the color intensities for red, green and blue. However, RGB colors are hardware dependent! If a RGB color cannot be displayed, it is mapped to another color (e.g. if a graphic card is restricted to 8-bit colors, it cannot display all 24-bit colors simultaneously. In this case, 24-bit color values currently unavailable in the color palette are mapped to a "best fit" color).

XBP_PP_DISABLED_BGCLR

This constant specifies a second background color to be used when an Xbase Part is disabled by calling the :disable() method. Normally, an Xbase Part is grayed when it receives the disabled status. This default color can be overriden for all Xbase Parts supporting a background color.

XBP_PP_COMPOUNDNAME

The value for this presentation parameter is usually a #define constant contained in the FONT.CH file. These constants provide for font definitions that are independent of the operating system. Valid values for this presentation parameter are also character strings that include the point size and the name of a font. For example:

aPP := { { XBP_PP_COMPOUNDNAME, FONT_DEFFIXED_SMALL } } 

aPP := { { XBP_PP_COMPOUNDNAME, "24.Arial" } } 

If a literal character string is used as value for this presentation parameter, it must include the font name in the very same way as it is listed in the font folder. Font names are case sensitive! In addition, the name of a font can differ depending on the language version of the operating system (If you don't get the font you have defined in your source code, compare the spelling of the font name in your PRG code with the spelling in the font folder).

XBP_PP_FONT

The value for this presentation parameter must be an XbpFont() object. If both XBP_PP_FONT and XBP_PP_COMPOUNDNAME are specified as presentation parameter, the parameter specified last defines the font.