FRX Cursor Foundation Class

Article
07/09/2007

This class provides methods to translate and manipulate various values in Label (lbx) and Report (frx) files.

Category	Reporting
Default Catalog	Visual FoxPro Catalog\Foundation Classes\Output\Output Helper Classes
Class	frxCursor
Base Class	Custom
Class Library	_FrxCursor.vcx
Parent Class	Custom

Remarks

This class exposes the algorithms used by ReportOutput.APP, ReportBuilder.APP, and ReportPreview.APP to interpret various printing values and Report (frx) and Label (lbx) table values.

It is primarily useful for developers extending Visual FoxPro reporting functionality. For more information, see Extending Report Functionality in Visual FoxPro.

FrxCursor helps you handle many details of the Report and Label file format that are otherwise obscure and, in many cases, very complex. The topic Understanding and Extending Report Structure will give you important details on this file format.

Important

Many methods of this class use a measurement unit known as a FRU. FRUs are FoxPro report units, specified as 1/10000 inch. This unit is the internal unit used by the Visual FoxPro Report Designer to store layout measurements and position. The methods of FrxCursor help you convert FRUs into units you can use more easily in other environments.

Properties, Events, Methods	Description
binStringToInt method	Returns the numeric equivalent of binary data encoded as a string of bytes. Syntax:`binStringToInt(cBytes)` Return: integer Arguments: cBytes provides the string of bytes for which the method returns the numeric equivalent. For example: `? oFrxCursor.BinStringToInt("ABC")` `* displays 4407873` An example of this method being called can be found in Report Protection Flags.
binToInt method	Converts a string of 1's and 0's into an integer. Syntax:`binToInt(cString)` Return: integer Arguments: cString provides the string of 1's and 0's for which the method returns the integer equivalent. For example: `? oFrxCursor.BinToInt(; "00000000000000000000000001111011") * displays 123`
charsetToLocale method	Converts a given fontcharset value to a candidate locale Id for use with the STRCONV() function. Parameters: nCharSet Syntax:`charsetToLocale(nCharSet)` Return: integer Arguments: nCharSet provides the fontcharset value to be converted.
createBandCursor method	Creates a cursor with alias "bands" from the FRX cursor, containing useful info about the bands in the report. Syntax:`createBandCursor([cFrxAlias]` Return: logical Arguments: cFrxalias provides the alias of the open Report table (frx) from which the "bands" cursor data should be derived. If the argument is omitted, the method assumes an alias of "FRX".
createCalcResetOnCursor method	Creates a cursor (alias "reset_on") containing records of information for each option in the Report Designer's Calculation Reset combobox. Refer to the Calculate Tab, Report Control Properties Dialog Box (Report Builder) topic for information on the available values. Syntax:`createCalcResetOnCursor( )` Return: logical Arguments: none.
createDefaultPrintEnvCursor method	Creates a one-record cursor with the same structure as the FRX, with the default printer environment data loaded into EXPR, TAG, and TAG2 fields. Syntax:`createDefaultPrintEnvCursor( [cFrxAlias` `[, cDestAlias ]])` Return: logical Arguments: cFrxAlias provides the alias of the open Report table (frx) from which the structure is derived. cDestAlias provides the alias for the one-record cursor the method creates. The default aliases are "FRX" and "defPrnEnv." Note The FRX source cursor's structure can have custom fields along with the standard Report table structure, and these fields will be duplicated in the resulting target (defPrnEnv) structure. Refer to Understanding and Extending Report Structure for more information.
createGroupCursor method	Creates a cursor with the alias "groups," derived from the FRX cursor, containing useful info about the report data grouping. Syntax:`createGroupCursor( [cFrxAlias])` Return: logical Arguments: cFrxAlias provides the alias of the open Report table (frx) from which the structure is derived.
createObjectCursor method	Creates a cursor with the alias "objects" from the FRX cursor, containing useful info about the layout objects in the report. Calls the createBandCursor method if necessary. Syntax:`createObjectCursor( [cFrxAlias[,cDestAlias [,iOption[,lRuntime]]]])` Return: logical Arguments: cFrxAlias provides the alias of the open Report table (frx) from which the structure is derived. The default is `"frx"`. cDestAlias specifies the destination alias of the cursor which will be created. The default is `"objects"`. iOption has the following possible values: iOption = 0 Default value if the argument is not included. Method includes all objects in frx, ignoring grouped items. iOption = 1 Includes only selected/CURPOS=.T. records in the cursor. iOption = 2 Includes all objects, showing grouped items as a single group record. iOption = 3 Provides a breakdown of grouped records. Note that some records included in a group may be marked deleted(). You can use SET DELETED ON to omit these records. lRuntime specifies that the object cursor should use report run-time values for each object's start band and end band. The default value is .F. which specifies that the band location values are correct as determined by the Report Designer layout engine. The report run-time engine uses different algorithms to determine which band a report layout element starts and ends in.
createVariableCursor method	Creates a cursor with the alias "vars" derived from the FRX cursor, containing useful info about the report variables defined in the report. Syntax:`createVariableCursor( [cFrxAlias])` Return: logical Arguments: cFrxAlias provides the alias of the open Report table (frx) from which the structure is derived.
fruToPixels method	Returns the size in pixels of a given number of FRUs. Syntax:`fruToPixels(iValue)` Return: numeric (number of Pixels) Arguments: iValue is an integer value providing the number of FRUs to be converted to a number of pixels.
getBandFor method	Returns an object representing the start or end band for a given object record. Since an object can span multiple report layout bands, this method provides either the start or end band in which the object is anchored. It uses the vertical offset position of the layout object to determine the correct bands. Syntax:`getBandFor(cUniqueID [,lStart])` Return: band object (the object represents the data in the FRX describing the relevant band) Arguments: cUniqueID is the FRX UniqueID value of the object for which you want band information. lStart indicates whether you want the start or end band.
getFruTextHeight method	Returns the height in FRUs of a text string displayed using a font with specified attributes. Syntax:`getFruTextHeight(cText,cTypeFace,iSize[, cStyle])` Return: integer value in FRUs. Arguments: cText is the string you want to measure. cTypeFace is the name of the font. iSize is the point size of the font. cStyle provides the styles you want to apply to the string, using the same values you would pass to the GETFONT( ) function. For more information, For more information, see AFONT( ) Function.
getFruTextWidth method	Returns the width in FRUs of a text string displayed using a font with specified attributes. Syntax:`getFruTextWidth(cText,cTypeFace,iSize[, cStyle])` Return: integer value in FRUs. Arguments: cText is the string you wish to measure. cTypeFace is the name of the font. iSize is the point size of the font. cStyle provides the styles you want to apply to the string, using the same values you would pass to the GETFONT( ) function. For more information, For more information, see AFONT( ) Function
getFrxTimeStamp method	Returns a time stamp for a given date/time, formulated according to the standards used in Visual FoxPro system tables (frx and lbx files, for reports and labels). Syntax:`getFrxTimeStamp([vDateTime])` Return: integer Arguments: vDateTime is an optional argument of either Date or DateTime type. If you omit the argument, the method uses the current DATETIME( ) value.
getMetadataDomDoc method	Returns an MSXml.DomDocument object containing the XML report memberdata for the current record in the FRX. If the STYLE field for the current record is empty, this method returns an empty template document of the appropriate XML schema. Syntax:`getMetadataDomDoc( [cFrxAlias])` Return: MSXml.DomDocument object, or NULL if the FRX alias is not USED(). Arguments: cFrxAlias provides the alias of the open Report table (frx) from which the structure is derived.
getObjectsInBand method	Returns a Collection of UNIQUEID values for each object that is contained by the specified Band. Syntax:`getObjectsInBand( cBandID [,lRecno])` Return: Object of Collection type, holding either UNIQUEID values for the selected layout objects or RECNO() values for the layout objects. Arguments: cFrxAlias provides the alias of the open Report table (frx) from which the structure is derived. lRecno indicates which type of values you want to have in the Collection. If you pass a second parameter of `.T.`, the collection is of FRX Record Numbers rather than the values in the UNIQUEID field.
getReportAttribute method	Returns a given attribute of the report header. Syntax:`getReportAttribute( cAttributeType, [,lAlternate])` Return: a Report attribute based on the argument supplied in the method call. Arguments: cAttributeType indicates the type of Report attribute value you want to receive. The following cAttributeType values are supported (case-insensitive): "UNITS" Returns an integer value indicating the units, as stored in the Frx.RULER field. Note This argument value can also return an associated string, representing the units, if you include the lAlternate argument with a value of `.T.`. For example, the following method call results in a return value of `"Inches"`: `oFrxCursor.getReportAttribute("UNITS",1)` "MULTICOLUMN" Returns a logical value. "COLUMNCOUNT" Returns an integer value. "PROTECTION" Returns a binary character string, which can be parsed to evaluate the different types of Report protection associated with this report on a global level. For more information, see Setting Protection for Reports
getSelectedObjectCount method	Returns the number of currently selected objects (objects with the CURPOS field value `set to .T.`) in the FRX cursor. Syntax:`getSelectedObjectCount( )` Return: integer. Arguments: none.
getTargetTypeText method	Returns a description of an FRX object's type, given the type and code values as stored in the FRX OBJTYPE and OBJCODE fields. Syntax:`getTargetTypeText(iType[,iCode])` Return: String. Arguments: iType provides the object's OBJTYPE value. If you omit this argument, or if you provide a value that is not one of the known OBJTYPE values, this method returns the string `Unknown Target type.` iCode provides the subsidiary OBJCODE value, used for FRX records with more than one type of record using the same OBJTYPE (primarily layout band records).
getTimeStampString method	Converts a Visual FoxPro time stamp into a readable string. Syntax:`getTimeStampString(iDateTimeStamp)` Return: String. Arguments: iDateTimeStamp is an integer in the format used by Visual FoxPro to store datetime stamps in system files (frx and lbx files, for reports and labels). For example: `? oFrxCursor.GetTimeStampString(819103384) * displays: 06/18/04 04:52:48 PM` Tip You can also use this method to examine the datetime stamp values in Visual FoxPro class libraries (vcx files).
getUnitValueFromFru method	Returns a given unit value for a given value in FRUs, depending on the units. Syntax:`getUnitValueFromFru(nFruValue, iUnits)` Return: numeric. Arguments: nFruValue is a number of FRUs, which may have decimal places. iUnits is an integer indicating the type of unit for which you want to receive the converted value. This value is determined by the integer values used in a report (frx) or label (lbx) table to specify ruler units. See Understanding and Extending Report Structure for more information.
hasBand method	Returns `.T.` if the report contains a band of the given type you specify. Syntax:`hasBand(iObjCode)` Return: logical. Arguments: iObjCode is an integer indicating the type of optional band for which you are checking. Tip Use this method to check for band types that do not occur in every report. For example, you can check for the existence of a Group band or a Summary band.
hasDetailHeader method	Returns `.T.` if the specified detail band record has an associated detail header record. Syntax:`hasDetailHeader(cDetailBandID)` Return: logical. Arguments: cDetailBandID is a string matching the Frx.UNIQUEID field value for the detail band you are investigating. Tip Detail Header and Detail Footer bands are optional. If you receive a .T. value for a Detail band, however, you can be certain that both Detail Header and Detail Footer bands are present; these bands are always paired.
hasProtectionFlag method	Returns `.T.` if the specified binary data has a specific flag set. Syntax:`hasProtectionFlag(cBytes,iFlag)` Return: logical. Arguments: cBytes is a string evaluated by this method as a series of bytes. iFlag is the bit value representing a type of report protection for which you are checking the report or report layout object.
insertBand method	Inserts a band of a given type into the currently selected work area. This method assumes that a valid FRX cursor is already selected and that its record pointer is located at the correct location for the insert operation. Syntax:`insertBand(iObjCode)` Return: logical. Arguments: iObjCode indicates the type of band record you want to insert in the FRX table.
insertDataEnvRecord method	Inserts a data environment object record into an FRX cursor. This method assumes that the record pointer is appropriately located. Syntax:`insertDataEnvRecord(cID,cName,cExpr,cCode)` Return: logical. Arguments: cID is the unique ID value for the new record's UniqueID column. cName is the value for the new record's Name column. cExpr is a list of name-value pairs to be included in the new record's Expr column. cCode is the text of method code to be included in the new record's Tag column.
insertDetailBand method	Inserts a Detail band into the currently selected work area. This method assumes that a valid FRX cursor is already selected and that its record pointer is located at the correct location for a Detail band record. Syntax:`insertDetailBand()` Return: logical. Arguments: none.
insertDetailHeaderFooter method	Inserts a Detail Header and Detail Footer band into an FRX cursor in the currently selected work area. This method assumes that a valid FRX cursor is already selected, and that its record pointer is located on a Detail band record that does not currently have Detail Header and Detail Footer bands. Syntax:`insertDetailHeaderFooterBand()` Return: logical. Arguments: none.
insertSummaryBand method	Inserts a Summary band into the currently selected work area. This method assumes that a valid FRX cursor is already selected and that that the FRX cursor does not already have a Summary band record. Syntax:`insertSummaryBand(lNewPage, lPageHeader, lPageFooter)` Return: logical. Arguments: lNewPage indicates whether the Summary band should start a new page. If the Summary band starts a new page, lPageHeader indicates whether the Summary page should have a Page Header band and lPageFooter indicates whether the Summary page should have a Page Footer band.
insertTitleBand method	Inserts a Title band into the currently selected work area. This method assumes that a valid FRX cursor is already selected and the FRX does not already have a Title band. Syntax:`insertTitleBand(lNewPage)` Return: logical. Arguments: lNewPage indicates whether the Summary band should start a new page.
intToBin method	Converts an integer into a string of 1's and 0's. Syntax:`intToBin(iInteger)` Return: String. Arguments: iInteger provides the integer for which the method returns a string of 1's and 0's. For example: `? oFrxCursor.IntToBin(123) * displays * 00000000000000000000000001111011`
intToBinString method	Returns a binary value encoded as a string of bytes for the integer you specify. Syntax:`intToBinString(iInteger)` Return: String (cBytes). Arguments: iInteger provides the integer for which the method returns a string of 1's and 0's. For example: `? oFrxCursor.IntToBinString(4407873) * displays ABC` An example of this method being called can be found in Report Protection Flags.
pixelsToFru method	Returns the size in FRUs of a given number of pixels. Syntax:`pixelsToFru(iValue)` Return: numeric (number of FRUs) Arguments: iValue is an integer value providing the number of pixels to be converted to a number of FRUs.
popPrintEnv method	Restores the printer environment from a previously saved cursor. This method assumes that the previously saved cursor is currently selected. Syntax:`popPrintEnv()` Return: logical. Arguments:none.
pushPrintEnvToCursor method	Saves the current printer environment to a cursor, which is created by this method. Syntax:`pushPrintEnvToCursor(cSavedInAlias)` Return: logical. Arguments:cSavedInAlias provides the alias of the cursor you want to create, and to which you want the printer environment saved.
screenDPI property	The DPI of the Report Designer. In VFP9 this is hard coded to 96, regardless of the actual display's DPI. Default: 96
setColumnCount method	Adds or removes columns (and column header/footer records) from the FRX cursor. This method assumes the FRX cursor is selected. Syntax:`setColumnCount(iColumns)` Return: logical. Arguments:iColumns sets the number of columns for the report layout.
stripQuotes method	Returns a string with embraced string delimiters removed. Syntax:`stripQuotes(cString)` Return: string. Arguments:cString is the value from which you want to strip delimiters. Note This method strips delimiting double-quotation marks (`"`) and single-quotation marks (`'`) but does not strip square brackets (`[` and `]`). It is designed to remove the delimiters that may have been placed in an FRX column's value by the native Report Designer. If square brackets delimit the value, the Report Designer did not add them.
synchObjectPositions method	Resets non-deleted objects in the FRX relative to the start of the band they are in after bands have been resized or repositioned in the layout. This method assumes that FrxCursor's bands and objects cursors have been created, that the currently selected table is a cursor of FRX structure, and that the method does not need to restore the record pointer after processing the records in the cursor. Syntax:`synchObjectPositions()` Return: logical. Arguments: none.

Example

This example changes the width of a field in a Report table record, to accommodate a different expression in this field.

It uses the FrxCursor.getFruTextWidth() method to determine the correct width for the new contents of the field. Then it uses the FrxCursor.getFrxTimeStamp() method to update the timestamp for this record.

#DEFINE OBJTYPE_FIELD           8
LOCAL iWidth, oFrxCursor
oFrxCursor = NEWOBJECT("FrxCursor", "_FrxCursor")
USE My.FRX
LOCATE FOR objtype = OBJTYPE_FIELD AND ;
           UPPER(ALLTRIM(Expr)) == "DATE()"
IF FOUND()
   iWidth = FrxCursor.getFruTextWidth(TRANSFORM(DATETIME()), ;
                                       fontface,fontsize)
   REPLACE Expr WITH "DATETIME()", ;
           Width WITH iWidth, ;
           Timestamp WITH FrxCursor.getFrxTimeStamp()
ENDIF

FRX Cursor Foundation Class

Remarks

Example

See Also

Reference

Concepts

Other Resources

Additional resources