Super Report Pro
Super Report Pro
Developer Manual
Version 3.1
e-Node
30 rue de la République
33150 Cenon
France
www.e-node.net
Copyright and Trademarks
All trade names referenced in this document are the trademark or registered trademark
of their respective holder.
4th Dimension, 4D Compiler, 4D, 4D Server, and 4D Client are trademarks of 4D SAS.
Contents
Copyright and Trademarks..................................................................................................... 2
About SuperReport Pro.......................................................................................................... 7
What is SuperReport Pro, and what can I do with it?............................................................. 7
SuperReport Pro Features.................................................................................................. 8
Technical Details............................................................................................................... 8
Compatibility Information.............................................................................................. 8
Technical Support......................................................................................................... 8
Upgrading from Previous Versions of SuperReport Pro............................................................ 9
Major differences from previous versions......................................................................... 9
Updating Commands................................................................................................... 11
Obsolete Commands................................................................................................... 11
Registering SuperReport Pro......................................................................................... 12
What’s New in SuperReport Pro Version 3....................................................................... 12
Setting up SuperReport Pro.............................................................................................. 15
Installation................................................................................................................ 15
Using SuperReport Pro in Demo mode........................................................................... 15
SuperReport Pro Variables............................................................................................ 15
Registering your SuperReport Pro Licence...................................................................... 16
The Demo mode dialog................................................................................................ 17
Registering Server licenses.......................................................................................... 19
Merged licenses notes................................................................................................. 20
License types............................................................................................................. 22
Getting Started with SuperReport Pro ................................................................................... 23
Creating SuperReport Pro Areas....................................................................................... 23
Using as External Window............................................................................................ 23
Using on a 4th Dimension Form..................................................................................... 23
Basic Integration............................................................................................................ 25
Using External Window................................................................................................ 25
Using Plug-in Area...................................................................................................... 26
Programming SuperReport Pro............................................................................................. 29
Commands and Functions................................................................................................ 29
Commands................................................................................................................ 29
Functions................................................................................................................... 30
When to use the commands and functions..................................................................... 30
Anatomy of a SuperReport Pro Command...................................................................... 31
Debugger.................................................................................................................. 31
Getters and Setters..................................................................................................... 31
Properties.................................................................................................................. 32
Customizing the SuperReport Pro Area.............................................................................. 33
Extending SuperReport Pro with Scripts............................................................................. 33
Execution Cycle scripts................................................................................................ 33
Object Scripts........................................................................................................... 34
SuperReport Pro Script Limitations................................................................................ 35
Understanding the SuperReport Pro Event Cycle................................................................. 36
Dealing with multi-platform Issues.................................................................................... 37
Dealing with platform pathnames.................................................................................. 37
Dealing with Print Drivers............................................................................................ 37
HTML Support................................................................................................................ 38
3
Table of Contents
4
Table of Contents
Printing......................................................................................................................... 70
SR_OpenSession (Session:L; DstFlags:L; DstPath:T; XML:T; JobName:T; Printer:T)
-> error:L.......................................................................................................... 70
SR_OpenSessionBLOB (Session:L; DstFlags:L; DstPath:T, XML:O; JobName:T;
Printer:T) -> error:............................................................................................. 71
SR_CloseSession (Session:L) -> error:L............................................................... 71
SR_Export (Src:T;Flags:L; DstPath:T; recordDelimiter;L) -> error:L.......................... 72
SR_ExportBLOBIntoBLOB (Src:O; Flags:L, FieldDelimiter:L; BLOB:O;
RecordDelimiter:L).............................................................................................. 73
SR_ExportIntoBLOB (Src:T; Flags:L; BLOB:O; recordDelimiter:L) -> error:L............ 73
SR_Print (Src:T; Flags:L; DstFlags:L; DstPath:T; Session:L; Printer:T) -> error:L....... 74
SR_PrintBLOB (Src:O; Flags:L, DstFlags:L; DstPath:T; Session:L; Printer:T; ioCount:L)
->error:L............................................................................................................ 75
SR_PrintSettings (ReportRef:L; Options) -> error:L............................................... 76
SR_PrintIntoPICT (Src:T; Flags:L; DstFlags:L; DstArray:AP; DstFormat:L; Printer:T)
-> error:L.......................................................................................................... 76
SR_PrintBLOBIntoPICT (Src:O; Flags:L, DstFlags:L; DstArray:AP; DstFormat:L;
Printer:T) -> error:L........................................................................................... 77
Miscellaneous................................................................................................................. 78
SR_ExecuteScript (ReportRef:L) -> error:L........................................................... 78
SR_Area_SaveUndo (ReportRef:L; Operation:L) -> error:L..................................... 78
SR_Area_AddUndo (ReportRef:L; Ref:L;OldState:L) -> error:L............................... 78
SR_Area_Undo (ReportRef:L) -> error:L............................................................... 79
SR_Area_Redo (ReportRef:L) -> error:L............................................................... 79
SR_ColorPicker (Color:L; ActionValue:L) -> ok:L................................................... 79
SR_DetokenizeScript (BLOB:O) -> text:T............................................................ 80
SR_RunScript (Text:T)....................................................................................... 80
SR_RunTokenizedScript (BLOB:O)...................................................................... 80
SR_TokenizeScript (Text:T; BLoB:O) ->length:L................................................... 81
Properties by Theme........................................................................................................... 83
Area/Plugin/Event Properties............................................................................................ 85
Area Properties.......................................................................................................... 85
Plugin Properties........................................................................................................ 86
Event Properties......................................................................................................... 89
Report Properties............................................................................................................ 90
Objects......................................................................................................................... 94
Object Properties........................................................................................................ 94
Group Properties........................................................................................................ 95
Line Properties........................................................................................................... 96
Oval Properties........................................................................................................... 96
Rectangle Properties................................................................................................... 96
Picture Properties....................................................................................................... 97
Text Properties........................................................................................................... 98
Text Style Properties .................................................................................................. 99
Variable Properties.....................................................................................................100
Variable Style Properties.............................................................................................101
Field Properties.........................................................................................................102
Field Style Properties.................................................................................................103
Table...........................................................................................................................105
5
Table Properties.........................................................................................................105
Header Properties......................................................................................................106
Header Style Properties..............................................................................................106
Column Properties.....................................................................................................108
Column Style Properties.............................................................................................109
Section........................................................................................................................110
Section Properties......................................................................................................110
Header/Footer Properties............................................................................................111
Section Break Properties.............................................................................................112
Watermark Properties.................................................................................................113
Guide Properties............................................................................................................113
Style Properties.............................................................................................................114
Data Source Properties...................................................................................................115
Appendixes.......................................................................................................................118
Appendix 1: Troubleshooting...........................................................................................118
Localised Formats......................................................................................................118
Appendix 2: Frequently Asked Questions..........................................................................119
Appendix 3: Hints and Tips.............................................................................................123
Quotes and Double Quotes..........................................................................................123
Printing....................................................................................................................123
Section Markers.........................................................................................................123
Windows Preview.......................................................................................................123
Index......................................................................................................125
What is SuperReport Pro, and what can I do with it?
SuperReport Pro's power does not come at the expense of simplicity. Most users will be
able to grasp the concepts involved in designing reports, since the editor is so similar to a
drawing program. Report operations like break processing, which can be cumbersome and
complex in 4D, are also made simpler, with the user able to specify when breaks occur and
which objects are to be totalled, without requiring any code.
• Compatibility with 4D v11 SQL, v12, and v13, including 64-bit 4D Server on
Windows. Note: On Mac, only Intel processors are supported.
• Include a full-featured reporting tool in any application, quickly and easily
• Enhance reporting capabilities using the SuperReport Pro developer API
• Complete support for creating HTML formatted reports
• Repeating objects for printing related many records
• Supports printing 4th Dimension arrays, including direct access to specific array
elements
• Support for executing callback routines and object scripts when printing reports
• Support for executing custom scripts for enhanced script management
• Support for custom structure views – great for isolating which tables and fields
the user can access
• Developer API for customizing end-user functionality
• Enhanced Editor Customization
• Print SuperReport Pro areas, or save them as HTML
Technical Details
Compatibility Information
SuperReport Pro Version 3 is compatible with 4th Dimension v11, v12, v13 and above, for
both Macintosh and Windows. It requires Mac OS 10.5 or higher and Windows XP SP2 or
better.
Technical Support
Technical support for SuperReport Pro is provided electronically via e-mail or our online
support reporting system. You are encouraged to use the online web reporting form as it
will be correctly routed to the appropriate support personnel.
www.e-node.net
Compatibility Mode
You do not have to update all your SuperReport Pro areas and code immediately;
SuperReport Pro version 3 will automatically run in compatibility mode.
2. SR Set Script Callback when used with area = 0 sets compatibility mode on
(in SuperReport Pro 3 it is a persistent property of the report, not a global one).
In compatibility mode, SRP_DataSource_Callback in the report is ignored; the
global setting is used.
What’s Changed
Native Look
Now the appearance is always native.
New API
SuperReport Pro version 3 introduces a completely new API which is based on a full list of
properties that the developer can get/set.
There are now fewer commands that you use to set and get an area’s properties. Each
command affects just one property for the area, making your code much easier to
understand and debug.
The new commands are organised into themes which relate to a particular part of the
SuperReport Pro area, and some miscellaneous Utility commands.
For each theme there is a group of “Getter” functions and “Setter” commands, each
targeting a different property type.
For example, you can use the SR_GetRealProperty command to get the value of a
property that has a real number value as its result.
Note that Boolean properties are called as longints (1 = True, 0=False).
Don’t worry though - you will not need to re-write all your SuperReport code.
Most of your existing commands will still work; the old commands act as wrappers for the
new ones. In fact you will still be able to write new code using the old commands, but if
you want to take advantage of the new features, you’ll need to use the new commands.
Some of the old commands are now obsolete or are no longer relevant and should be
removed from your code.
These are listed in the table below, along with details about how they should be replaced,
where appropriate.
You can find a description of the new syntax in the Anatomy of an SuperReport Pro
Command topic.
Updating Commands
The new API supports many more options and object types. You may want to replace calls
to old functions with their new versions. Following are some examples:
$error:=SR_GetPtrProperty (vSRArea;lSR_ObjID;SRP_Field_Script;
->tSR_ObjScript)
$error:=SR_GetPtrProperty (vSRArea;lSR_ObjID;SRP_Column_Script;
->tSR_ObjScript)
lSR_ObjTop:=0
$error:=SR_GetPtrProperty (vSRArea;lSR_ObjID;SRP_Object_PosTop;
->lSR_ObjTop)
You can find a list of all the object property options in the Object
Properties section.
SR Get Sections Use SR_GetPtrProperty with the appropriate property. For example, to
get the name of a section:
lSR_SectName:=""
$error:=SR_GetPtrProperty (vSRArea;lSR_ObjID;SRP_Section_Name;
->lSR_SectName)
You can find a list of all the section property options in the Section
Properties section.
Obsolete Commands
If you are using any of the following commands, you will need to remove them from your
code or modify them as explained in the Comments:
Count Pages
A count pages option (SRP_Report_CountPages) has been added, so now you can use
"Page 1 of 9" for example (however, note that the report is processed three times).
Dynamic Text
Text objects can use "<% [+] [=] variable [ ; format ] %>" when SRP_Text_Dynamic = 1
Group object
Objects can now be grouped together by selecting them and clicking on the Group Object
tool in the toolbar.
HTML Export
The HTML export has been improved.
Multiple headers/footers
A multiple headers/footers option has been added (first page/second+ pages/last page).
To function properly on the last page, SRP_Report_CountPages must be set to 1 (if count
pages is 0, it will never print).
Object Properties
Objects have new properties - name, id - which can be used in XML/HTML exports.
Scripts
Scripts now support flow control structures (but you must not use local variables).
Scripts are stored tokenized, eliminating problems between various localized 4D versions
(e.g. the English version no longer fails to run the French demo due to the command
names).
Table object
A new object has been added to the toolbar: the Table Tool. Use this to create tables within
your report.
Unicode
SuperReport Pro supports Unicode for display and data entry. Note that filters were not
changed to support Unicode, so their functionality is limited to Roman characters.
In other words, if a filter is specified, non-Roman characters cannot be entered.
Watermark section
A Watermark section has been added. The watermark will be printed on every page, either
underneath or on top of all other printing.
XML
An area’s settings can be saved as XML into a variable or field. Note that if 4D is run in
non-Unicode mode, the size of any text is restricted to 32k characters. This may be enough
as long as you don't have any large pictures in the report, however, it is recommended
that you use the application in Unicode mode. Use the old commands for loading/saving
reports (using BLoBs) if you have to run in non-Unicode mode.
Other Improvements
You'll also notice many additional little improvements and new features such as "center
object on page", "bind object to bottom of a group/section", "print break footer at bottom
of page, not below body", and other goodies.
Installation
SuperReport Pro is provided as a bundle for both Windows and Mac OS: there is just one
version for both platforms, including Windows 64-bit. To install it, simply copy the file
SRP.bundle into your Plugins folder.
Plugins folders can be located in one of two locations:
• In the 4D application folder (4th Dimension or 4D Server). When plugins are
installed in this location, they will be available to every database that is opened
with that application.
• Next to the database structure file for your project: In this case, the plugin will
only be available to that database. On Mac OS, this means that the Plugins folder
must be placed within the database package. To open the package, ctrl-click on
the package and choose Show Package Contents from the contextual menu.
Using SR_Register
1. Open the On Startup database method
2. Call the SR_Register function with your registration key - for example:
$result:=SR_Register("YourRegistrationKey") // result = 0 means registration was successful
If you have several licenses for different 4D setups you can call SR_Register multiple
times in a row without further testing.
The Demo mode dialog includes all relevant information to obtain your license, as well as
a “Copy” button to put this information into your clipboard or a text file, an “eMail” button
to email the information to e-Node's registration system and a “Register” button to enter
your license key once received:
Paste or drag and drop your registration key and, if correct, the plug-in will be registered
for all future uses on this workstation:
Note: if 4D does not activate the Edit > Paste menu item click Abort and Register again.
The text file must be called "SRP3.license4Dplugin" and be a plain text type file.
Just paste all your licenses for SuperReport Pro v3.x, one per line, e.g.:
MyLicense1
MyLicense2
MyLicense3
Any license type can be included into this document, except unlimited single user, OEM
and Partner licenses.
Note: the Demo mode dialog Register button actually does this: create the text file and
include the license key, or add the license key to the existing document, if any.
Mixing methods
When such a file exists in the Licenses folder SuperReport Pro will check for valid
licenses from this document as a first action before anything else (including checking any
SR_Register command).
If a valid license is included into the "SRP3.license4Dplugin" document any calls to
SR_Register will return zero (for "OK").
Therefore you can mix modes and use the text file (or Register button) as well as the
command.
Unlimited single user, OEM, temporary and Partner licenses can only be entered through the
SR_Register command.
Use the Copy, eMail and Register buttons just as above and your server will be registered
for all workstations.
Note that any other workstations previously connected (before registration occurred) will
need to re-connect to the server to be functional.
Registering on 4D Server
To directly register the server and all workstations from the server machine itself, you
need to display the Demo mode dialog on the server.
Call SR_Register with an empty string in the On Server Startup base method:
C_LONGINT ($result)
$result:=SR_Register ("") // display the dialog
Use the Copy, eMail and Register buttons just as above and your server will be registered
for all workstations.
Note that the dialog will automatically be dismissed on the server after one minute in
order not to block client connections (the server is only available to client workstations
once the On Server Startup method has completed).
Note that merged licenses will keep working if your 4D Server serial information is modified
(upgrading or 4D Partner yearly updates), or if any client workstation hardware is changed.
It will only have to be updated if the 4D Server hardware is changed, or if the plugin itself
requires a new key (paid upgrades upon major version changes).
You may want to register your merged server without having to turn off the database to
modify the code. We have created a utility database to manage this - it's called Get Serial
Info and you can download the appropriate version for your 4D version from the e-Node
server.
This is possible using any 4D setup on the server machine (such as a standard developer
single user 4D). Keeping your production server alive, open the Get Serial Info database
with 4D on the same server machine. Ignore the demonstration mode dialog (if your
single user 4D is not registered for the plugin) and wait for the next Alert:
A text file is also saved with the same information. The last line “Machine ID” is the number
that you need to send in order to receive your merged server registration key.
License types
Eight license types are available:
• Single-user license. This license allows development (interpreted mode) or
deployment (interpreted or compiled mode) on 4D Standalone or 4D SQL Desktop.
Since the registration key is linked to a specific 4D license, you need to provide
the number returned by the 4D command GET SERIAL INFORMATION (first
parameter). A new license will be supplied for free at any time if you change your
4D version and / or get a new 4D registration key, provided that your previous
licenses match the current public version at the exchange time.
• Small server: This license allows development (interpreted mode) or deployment
(interpreted or compiled mode, including merged servers) on 4D Server with
up to 10 users. The registration key is linked to your 4D Server license just as
above, or to the server machine for merged server applications.
• Medium server. This license allows development (interpreted mode) or
deployment (interpreted or compiled mode, including merged servers) on 4D
Server with 11 to 20 users.
• Large server. This license allows development (interpreted mode) or deployment
(interpreted or compiled mode, including merged servers) on 4D Server with
over 20 users.
• Merged single user. This license is designed for single user compiled/merged
applications built with 4D Unlimited Volume Desktop (one license per workstation).
It is linked to the workstation, not the 4D serial number.
• Unlimited Single User. This license allows development (interpreted mode) or
deployment (interpreted or compiled mode) on any number of 4D Standalone,
Runtime or Engine copies that run your 4D application(s). This is a yearly license,
which expires after the date when it is to be renewed. The expiration only affects
interpreted mode. Compiled applications using an obsolete license will never expire.
• Unlimited OEM: This license allows development (interpreted mode) or
deployment (interpreted or compiled mode) on any number of 4D Servers (of
any number of users), 4D Standalone, 4D SQL Desktop or merged copies that
run your 4D application(s). This is a yearly license, which expires after the
date when it is to be renewed. The expiration only affects interpreted mode.
Compiled applications using an obsolete license will never expire.
• Partner license: This license matches 4D's annual Partner subscription and
covers all the plug-ins published by e-Node, including AreaList Pro, SuperReport
Pro, PrintList Pro and CalendarSet. A single registration key allows development
(interpreted mode) or deployment (interpreted or compiled mode) on all 4D
Standalones and 4D Servers (2 users) provided by your 4D Partner license.
No merged applications. This is a yearly license, which expires on February 1st
(same date as your 4D Partner licenses). The expiration only affects interpreted
mode. Compiled applications using an obsolete license will never expire.
For current pricing, please see the ordering page on our website.
For detailed information on using the SuperReport Pro commands, please refer to the
Command Reference section.
C_LONGINT(iSR_Win)
iSR_Win:=Open external window(50;50;400;400;8;”SuperReport Pro”;”%SuperReport”)
2. Draw a rectangle on the form in the size that you want your report to appear.
3. In the Properties palette, choose SuperReport Pro from the Type dropdown
menu
4. Assign a name to the object variable
Your SuperReport Pro area will look like this:
Note that if you have a field in the table that has the same name as the report variable
followed by an underscore, the comment changes:
The field must be a BLoB or Text field. Otherwise, you'll see the following comment:
For more detailed information on using SuperReport Pro on an input form, please refer to
the Tutorial section in the SuperReport Pro User Guide.
You can use the commands and functions to configure every aspect of an SuperReport Pro
area, and to get information about an area. The commands and functions are grouped into
themes such as Getters, Setters, Printing etc.
Basic Integration
SuperReport Pro can be integrated into your applications via two different methods. The
first method uses a 4th Dimension external window; the second uses a 4th Dimension form
that can be displayed in a dialog or input form.
All examples discussed in this section assume you have a custom table for storing the
various reports you create. In our examples, we’ll use the following table structure, which
is defined in the Demo Database that is supplied with SuperReport Pro:
When you display SuperReport Pro in an external window, you should use a Window type
of 8 so that the window can be resized by the user and the close box is available. If you
use a modal window (type 1 or type 5), the user will not be able to close the window.
2. If you wish to communicate with the SuperReport Pro editor in an external
window, you can use the window reference (iSR_Win) as the area reference
parameter for those routines which interact with the plug-in area.
C_TEXT(tReportDoc)
tReportDoc:=”Hard Disk:myReport.srp”
iSR_Err:=SR_NewReport (iSR_Win;tReportDoc;1)
1. Create a new input form, or modify an existing input form, in which you wish to
display the SuperReport Pro plug-in area.
2. Create a new plug-in object using the 4th Dimension Object List:
3. Select the SuperReport Pro object from the Plug-in Area popup menu to create
a SuperReport Pro area.
4. Assign a name to your variable, which will be used by the related SuperReport
Pro command to reference your report area.
If you define the name of the report area which is the same name followed by an underscore
of a field which is in the table which contains the form you have created, SuperReport Pro
will automatically load and save the report when the record is loaded.
For example, if you have a field entitled [Reports]ReportData_ when creating the
SuperReport Pro area, using a name of “ReportData” will instruct SuperReport Pro to
automatically load/save the report when the record is loaded and the form is displayed.
The type of this field should be a BLoB field.
If you are using the auto save feature of SuperReport Pro, you may proceed to Step 7.
If you are not using a “report” table, you will need to procedurally load/save the reports
using the appropriate SuperReport Pro routines (Step 5 and Step 6).
5. The next step is to create the report data so that your users can access it. The
first If test determines if it's a new record. If so, we create a new report using
the SR_LoadReport command. If it's an existing record, we load the data from
the saved report record with SR_ParseReport (we’ll cover how to save report
data in a bit).
C_LONGINT($err)
Case of
:(Form event=On Load)
If (Is new record([Customer])) // it's a new record
$err:=SR_LoadReport (vSRArea;SR_GetTextProperty (0;0;SRP_Area_NewReport))
Else
$err:=SR_LoadReport (vSRArea; BLOB to text ([RM_Reports]RM_ReportData;
UTF8 Text without length))
End if
End case
At this point, we are ready to begin using the SuperReport Pro editor. However, before we
proceed, let’s add the code necessary for saving your report information to our report data
field so that we can access it again.
6. The last step we need to complete is saving our reports to the SuperReport
Pro data field. The easiest way to do this is to make sure you have a field,
appropriately named, to auto-save the report (see the discussion on this topic)..
When you are retrieving information from a SuperReport Pro plug-in area, you must
use a 4th Dimension text variable; passing a text field will not work correctly. Once the
SR_SaveReport routine has completed successfully, you can copy the variable to your
storage field as we have above.
7. Now you are ready to begin using the SuperReport Pro editor. Enter the User
Mode (or however you have configured access to the Report_Mgr table) and
create a new record. You should see something similar to the following input
form:
Commands
The commands are organised into themes which relate to a particular part of the
SuperReport Pro functionality: Access, Getters, Setters, Area Properties, Printing, and
Miscellaneous. The “Getter” and “Setter” commands are used to set the various properties
of the report, and to find out what the specific settings are, or what action the user has
taken. For example, you can find out the name of a specified object on a report with the
SR_GetPtrProperty "getter":
$error:=SR_GetPtrProperty (vSRArea;lSR_ObjID;SRP_Object_Name;->tSR_ObjName)
Note that Boolean values are passed or returned as longints, where 1 = true and 0 = false.
You can find complete descriptions of the commands, along with examples, in the Command
Reference section, and descriptions of all the properties in the Properties by Theme section.
The Properties by Theme section includes details of how to use each property; the Type
column tells you what type of data it requires, and this is matched to the command variant.
Functions
Functions return a result code when they are called. Usually this will be the information
you requested.
Their syntax looks like this:
SR_GetObjects ($report;1;SRP_ReportSections;$alObjectID)
SR_GetTextProperty ($report;$alObjectID{1};SRP_Object_Name)
id is a constant that tells SuperReport Pro exactly what information you want to get (see
the Properties by Theme section to find out what the possible constants are).
Value is the result that the function returns
For example, suppose we want to find out which tool the user selected. We can use the
SR_GetLongProperty "getter" function to find out:
C_LONGINT($ToolSelected)
$ToolSelected:=SR_GetLongProperty (vSRArea;1;SRP_Area_Tool)
ARRAY TEXT($aPropID;0)
ARRAY TEXT($aPropValue;0)
ARRAY TEXT($aPropName;0) // (this is the optional one)
$error:=SR_GetProperties (SRArea;0; $aPropID;$aPropValue;$aPropName)
If the function executed successfully, $error will be 0; if not, $error will contain an error
number. You can check the meanings of the error codes in the Result Codes list.
Every command consists of the command name followed by two or more parameters.
The first parameter is always a reference to the SuperReport Pro area. For example, the
SR_SetRealProperty command sets a specific property that requires a real number:
SR_SetRealProperty (SR_AREA;1;SRP_Report_Scale;$reportScale)
This command sets the scaling for the SuperReport Pro SR_AREA to the value specified in
the $reportScale variable.
Commands that get or set properties for an object all include the property that you want
to affect, and a value to use to specify an option (if it’s a “setter”) or to receive the result
(if it’s a “getter”). See the section on Getters and Setters, below.
All SuperReport Pro commands are described in the Command Reference section along
with examples of how to use them.
Debugger
When the SRP_Area_TraceOnError property is set to True (the default), if there is an error
in a command that does not return an error code, and you are using 4D in interpreted
mode, the 4D debugger window will automatically open with the line immediately following
the problem line highlighted.
each available in five variants, which allow for the different data types of the properties:
Longinteger, Pointer, Real, Text, and Arrays.
For example, to set the "show ruler" property for a report, you use the SR_SetLongProperty
command along with the SRP_Report_ShowRuler property:
SR_SetLongProperty (SR_AREA;1;SRP_Report_ShowRuler;1)
Example
Let’s suppose that we want to find out which tool the user has selected. You can use the
SR_GetLongProperty getter along with the SRP_Area_Tool property:
C_LONGINT($toolId)
$toolId:=SR_GetLongProperty (MyReport;1;SRP_Area_Tool)
Properties
Each command theme has its own set of properties that can be used to get or set various
aspects of the area, and for each property a 4D constant has been defined.
You’ll find a complete reference in the Properties by Theme section.
In your form's On Load event, call one or more of the Setter commands with the properties
you want to set.
The checkmark next to the Start Script ... option in this example indicates that a Start
Script has been added.
You can find an example of using scripts in the Tutorial section of the User Manual.
Object Scripts
Like standard 4th Dimension reports created using the Form Editor, SuperReport Pro objects
may contain scripts which may call any 4th Dimension command, method, or 3rd Party
plug-in routine. Using SuperReport Pro scripts, you can further customize your reports to
produce output which cannot be created using standard SuperReport Pro objects.
For example, let’s say you wanted to create a report with a listing of sales, broken down
by customer, and provide an average sale for each customer as well as an overall invoice
average. While SuperReport Pro can handle most of these tasks for you, utilizing the
advanced break processing capabilities built-in to SuperReport Pro, the extended averaging
requirements would not be possible without the support of object scripts.
Using SuperReport Pro’s object scripts, you can place custom code on just about any
SuperReport Pro object, including section lines, providing a very complete and flexible
reporting system.
To add a script to an object, double-click on the object. The object properties dialog will
open; the exact contents of the dialog vary depending upon the type of object, but they
will all have a Script option. For example, the Field Properties dialog looks like this, with
the Script tab selected:
3. When selecting a table or field which has been customized (using SuperReport
Pro’s structure customization feature), the script editor will display the actual
table/field information as configured at the structure level.
Execute StartProcedure
Determine how many iterations are required
While (Current Iteration < Maximum Iterations) do
Execute BodyProcedure
If (Break Values have changed)
Process appropriate SubHeader sections
Process appropriate SubTotal sections
End if
Process Body section
End while
Process Total section
Execute EndProcedure
Section Processing
In processing any section, the following sequence of events takes place:
Then you could use the 4th Dimension function Application file or Structure file to return
the pathname to either the application or structure file as a starting point to determine the
pathname to a “Reports” directory.
For some useful routines for obtaining the parent pathname for an application or structure
file, refer to the 4th Dimension Language Reference.
HTML Support
SuperReport Pro provides the ability to create standard HTML reports.
Each SuperReport Pro object may contain custom HTML tags, which are inserted before
and after the corresponding data object is sent to the HTML file when printing the report
in HTML format.
Using the HTML Tag Dialog, you can supply the following items:
• Begin Tag
The begin tag information is sent to the HTML file before the corresponding data
is sent to the file.
• End Tag
The end tag information is sent to the HTML file after the corresponding data is
sent to the file.
NOTE: the font is not exported (SuperReportPro 2.5 did use <font face="xxx">)
There are three ways to print your reports in HTML format. The first method uses the
SuperReport Pro Editor.
1. Select Export… from the File menu.
2. Select Output As HTML File in the Output Options section:
The second method is to use the SR_Export command with the SRP_Export_HTML option
- for example:
C_BLOB(oSR_Report)
SET BLOB SIZE(oSR_Report;0)
SR_ExportIntoBLOB ($Report;SRP_Export_HTML; SRP_Export_Body;oSR_Report)
See the Tutorial section in the User Guide to learn more about getting started with
SuperReport Pro.
C_LONGINT($err;$i)
C_LONGINT($report;$section;$object)
$err:=SR_NewReport ($report;"";0)
SR_SetTextProperty ($report;1;SRP_Report_Name;"ALP")
SR_SetLongProperty ($report;1;SRP_Report_PageWidth;595) // A4
SR_SetLongProperty ($report;1;SRP_Report_PageHeight;842) // A4
SR_SetTextProperty ($report;1;SRP_Report_Margins;"12.5;12.5;12.5;12.5")
$object:=SR_GetLongProperty ($report;1;SRP_Report_DataSource)
SR_SetLongProperty ($report;$object;SRP_DataSource_Source;SR Iterations Fixed)
SR_SetLongProperty ($report;$object;SRP_DataSource_Iterations;1)
$err:=SR_NewObject ($report;$object;SRP_Style;0)
$err:=SR_NewObject ($report;$object;SRP_Style;0)
// Create a Table object in the body - the table which will be filled by AL_SuperReport
$err:=SR_NewObject ($report;$object;SRP_Table;$section)
SR_SetLongProperty ($report;$object;SRP_Text_PosWidth;570)
SR_SetLongProperty ($report;$object;SRP_Text_PosHeight;40)
SR_SetLongProperty ($report;$object;SRP_Table_NumHeadings;1) // one line in header - this
should not be needed
SR_SetLongProperty ($report;$object;SRP_Table_NumColumns;1) // one column - this should not
be needed
SR_SetLongProperty ($report;$object;SRP_Text_Align;2) // center on page
ARRAY LONGINT($aObjects;0)
$err:=SR_GetObjects ($report;$object;String(1;SRP_TableHeaderRowMask);$aObjects) // get the
first header line objects
SR_SetLongProperty ($report;$aObjects{1};SRP_Style_StyleID;1)
$err:=SR_GetObjects ($report;$object;SRP_TableColumns;$aObjects) // get the columns
SR_SetLongProperty ($report;$aObjects{1};SRP_Header_StyleID;2)
// test it
C_LONGINT($win)
$win:=Open external window(100;100;800;800;Plain form window;"SRP";"%SuperReport")
$err:=SR_LoadReport ($win;$xml;0)
How it works
AreaList Pro v9.4 and above allows printing or saving as HTML through SuperReport Pro
v3. It only takes two lines of code to print an AreaList Pro area.
Additional options are available, such as automatic column width and use of SuperReport
Pro style properties instead of the existing AreaList Pro area settings.
You can either use the built-in SuperReport Pro template to print an AreaList Pro area “on
the fly” or create your own.
The AreaList Pro Demonstration database includes a “Print with SuperReport Pro” button
in the AreaList Pro > Configuration Options… dialog. It also includes a SuperReport menu,
allowing printing with the default template or a custom template, and editing / creating
your own templates.
Use the following property with AL_GetAreaTextProperty to retrieve the default template
in XML format:
Constant Get Set Per Type Default Min Max Comments
ALP_Area_ text Get the SuperReport Pro template used
SRPTableTemplate for report creation (stored in Resources/
TableReport.xml) as XML
Example
$reportXml:=AL_SuperReport ($area;"";1;SRP_Style_HasFontName | SRP_Style_HasFontSize;
"My first ALP area printed using SRP")
The code above means: fill the template but don't use the font name and font size defined
in AreaList Pro (use the one stored in the template default style), columns will be auto-
sized by SuperReport Pro (because the fonts are different, the AreaList Pro widths must
be ignored)
Then use SuperReport Pro to edit the resulting report, save it, export it as HTML or print
it, e.g.:
$result:=SR_Print ($reportXml;0;SRP_Print_DestinationPreview | SRP_Print_AskPageSetup; "";0;"";0)
Custom templates
AreaList Pro’s built-in SuperReport Pro template is obtained by the
ALP_Area_SRPTableTemplate property, which gets the SuperReport Pro template that will
be used for report creation by AL_SuperReport (stored in Resources/TableReport.xml)
as XML:
$tableReportTemplate:=AL_GetAreaTextProperty (0;ALP_Area_SRPTableTemplate)
//get the built-in SRP template from ALP
Then in SuperReport Pro you can edit and save your own template anywhere (in the data
file or a document) for future use with AL_SuperReport, e.g.:
$srpError:=SR_LoadReport ($window;$tableReportTemplate;0)
// load the SRP report and display it, save the custom template somewhere with the File menu
Demonstration database code examples (from the AreaList Pro demo database)
Style Tag
Bold <b>
Decrease font size by # quarters (1/4) of current size <s -#>
Increase font size by # quarters (1/4) of current size <s +#>
Inserted text <ins>
Italic <i>
Strike-through <del>
or
<SPAN STYLE='text-
decoration:line-through'>
Set font size to # points <s #>
Set font by name <f "font name">
(needs to be quoted if the name
contains more than one word)
Set color (any format can be used, e.g. <c 0xFFFF0000> <c color name>
<c 1.0,0,0> <c P123> <c dark orange>)
Underline <u> or <ins>
4D v12 (and above) internal format for styled text is stored as <SPAN STYLE="style attributes">
where the style attributes used by SuperReport Pro are:
• font-family
• font-size
• font-weight (bold/normal)
• font-style (italic/normal)
• text-decoration (underline/ line-through/none)
• color (#RRGGBB).
It is also possible to set the format as attributed, and specify the style attributes using the
SRP_Variable_Attributed and SRP_Variable_Format properties.
This feature is usable with Variable, Field and Table’s Column types objects.
Example:
C_TEXT($format)
SR_SetTextProperty ($area;$object;SRP_Variable_Format;"$format)
Here is the result, using a repeating variable/field with that format, or as one column in a
Table object (with variable row height to hold the taller ZERO value):
Note that if the number format is too “small” to hold the number, 4D (and SuperReport
Pro) will display it as “<<<<<<<<<<<<<<<<<<”, which will interfere with the opening
tag character “<” if the column is attributed (multi-styled).
In the example above (using "## ###" as a number format), this will be the case for all
numbers exceeding 99,999.
Make sure that the format used will not cause the number to overflow, lest unexpected
results might ensue.
Commands by Theme
inCallback command
text SRP_DataSource_Callback property.
53 Commands by Theme
Parameters
Parameters
Every command requires at least one parameter. Most require the first parameter to be
the area reference: this is the Variable Name that you assigned to the SuperReport Pro
area that you want the command to affect:
Result/Error Codes
Functions return a result after they have been called. Unless otherwise specified in the
parameter description table, the result codes are long integers and have the following
meanings:
54 Commands by Theme
Parameter Descriptions
Parameter Descriptions
Each command has its own set of parameters, and they are each described in the parameter
descriptions table. The tables comprise three columns: Parameter, Type, and Description.
Parameter: The name of the parameter, as shown in the Parameter list. Each is preceded
by one of two arrows which indicate whether it is a value that you pass to the command
or one that the command returns to you:
Type: The type of the parameter. Note that if your database is running in non-Unicode
mode, text objects are limited to 32k characters.
Description: Information about the parameter
Command Description
An explanation of what the command does and how to use it.
Examples
One or more examples demonstrating how the command might be used.
55 Commands by Theme
Command Themes
Command Themes
The commands are organised into six themes:
Access: Commands that affect the entire SuperReport Pro area
Getters: Commands for getting information about certain aspects of the report
Setters: Commands for setting properties of objects on the report
Objects: Commands for managing the various objects on the report
Printing: Commands to manage the printing of SuperReport Pro reports
Miscellaneous: Some additional tools and utilities.
For each theme there is a set of properties that can be used with that theme’s commands.
You will find a complete list of properties in the Properties by Theme section.
Access
The commands in this theme affect the overall SuperReport Pro area.
The properties that can be used with these commands can be found in the Properties by
Theme section.
For the Area properties pertaining to areas (e.g. SRP_Area_DrawingMode), not global
settings, you can use 0 as the Area Reference to accessing the default values for all newly
initialized (or re-initialized) areas.
• ReportRef = 0 means "access workstation global settings".
• ReportRef # 0 means "access this area's settings".
ReportRef is either a Report reference (from SR_NewReport) or a SuperReport Pro area reference
Ref is the object number, where 0 = selected objects, 1 = the report itself
%SuperReport
The actual plug-in area object, which is placed on the 4th Dimension form in which you
wish to display the SuperReport Pro area.
In addition, you use the %SuperReport routine when using the 4th Dimension Open
external window function, which provides the ability to display the SuperReport Pro
editor in a standard 4D external window. For example:
56 Commands by Theme
Examples SR_Register
SR_Register is used to register the SuperReport Pro plug-in for standalone or server use.
You must call SR_Register with a valid registration key, otherwise SuperReport Pro will
operate in demonstration mode - it will cease to function after 20 minutes.
When SR_Register is called with an empty string, the license dialog will be displayed if
SuperReport Pro is not registered and the dialog had not yet been displayed.
Multiple calls to SR_Register are allowed. The plug-in will be activated if at least one valid
key is used, and all subsequent calls to SR_Register will return 0.
Example
C_LONGINT ($result)
$result:=SR_Register ("YourRegistrationKey")
Case of
:($result=2)
ALERT ("The SuperReport Pro licence is invalid.")
:($result=3)
ALERT ("The SuperReport Pro licence has expired.")
etc.
End case
57 Commands by Theme
Examples SR_ConvertToXML - SR_LoadReport
Alternatively to SR_Register, you can place a plain text file into your 4D Licenses folder.
Please see the Licence Types section for detailed information about the licencing options
available for SuperReport Pro.
Example with multiple calls
C_LONGINT ($result) // ignored in this case
$result:=SR_Register ("Registration key one")
$result:=SR_Register ("Registration key two")
$result:=SR_Register ("Registration key three")
etc.
Convert a SuperReport Pro report template from BLoB (SuperReport Pro 2.x document or
SuperReport Pro 3.x XML in a blob (UTF8 or UTF16LE)) to text in XML format.
Note: SR_ConvertToXML is used internally when needed - you don't have to convert all
old reports to use them.
Example
Convert a report that has been saved in a BLoB field into XML:
C_TEXT(tReportXML)
$err:=SR_ConvertToXML([Reports]ReportBlob;tReportXML;"MyReport";CallbackMethod)
58 Commands by Theme
Examples SR_NewReport - SR_NewReportBLOB
Example
This example opens a report that has been saved in a BLoB field:
$report:=BLOB to text([Reports]ReportBlob;UTF8 text without length)
If (Length($report)>0)
$err:=SR_LoadReport ($ReportArea;$report;0)
End if
Example 2 - Create a new offscreen report and load a report from a BLoB field:
C_LONGINT($SR_Err;$newReportArea)
$report:=BLOB to text([Reports]ReportData;UTF8 text without length)
$SR_Err:=SR_NewReport ($newReportArea; $report;1)
59 Commands by Theme
Examples SR_SaveReport - SR_DeleteReport
Save the contents of the defined report to a file or as XML in a variable. This command is
equivelant to selecting Save to Disk menu item from the File menu in the SuperReport Pro
report area.
Example 1: Save a report to a field
tReport:=""
iSR_Err:=SR_SaveReport (report_area;tReport;1) // save the report data to a variable
If (iSR_Err=0) //if the command completed successfully
[Customer]customer_report:=tReport
End if
Delete an offscreen report created with SR_NewReport. You should be sure to always
delete offscreen reports after you've finished with them.
Example
$err:=SR_DeleteReport ($newReportArea)
60 Commands by Theme
ExamplesSR_GetObjectXML - SR_GetProperties
Getters
Use these commands to get information about a report. For a list of properties, see the
Properties section.
Get the XML value of the specified object(s) and store it into a text variable.
Note: because a text array is used for values, pictures and BLOBs are unusable and real
numbers use decimal point regardless of the current system settings. Also, when operating
on multiple objects (selection), only properties common to all objects are returned and
when there are different values for a property, "<multiple values>" is returned.
61 Commands by Theme
ExamplesSR_GetPtrProperty - SR_GetLongProperty
Value pointer
Get the value of a property using a pointer. For a list of properties, see the Properties
section.
Example 1 - using a BLoB
C_BLOB($blob)
$error:=SR_GetPtrProperty (vSRArea;1;SRP_Report_UserBLOB;->$blob)
Value longint
Get the value of a longint property. For a list of properties, see the Properties section.
Example
Find out which tool in SuperReport Pro's toolbar the user has selected:
$toolId:=SR_GetLongProperty ($SRArea;1;SRP_Area_Tool)
62 Commands by Theme
ExamplesSR_GetObjects - SR_GetRealProperty
* Usage is in the "creating report programmatically": use that mask and add the header
row number (starting at 1): String ($row; SRP_TableHeaderRowMask). So for example the
third header line is "H003".
Value real
Get the value of a real property. For a list of properties, see the Properties section.
Example
Get the current DPI setting on the X axis for the repport:
C_REAL($DPI_x)
$DPI_x :=SR_GetRealProperty($report;1; SRP_Area_DPI_X)
63 Commands by Theme
ExamplesSR_GetTextProperty
Value real
Get one text property of an object. Use ReportRef = 0 and Ref = 0 to access a global plugin
property (such as SRP_Area_Path)
Example
Get the name of the area object (the area's variable name used on the 4D form):
C_TEXT($AreaVariableName)
$AreaVariableName :=SR_GetTextProperty($report;0;0)
64 Commands by Theme
Examples SR_SetPtrProperty - SR_SetLongProperty
Setters
Example
Clear the page setup settings for a report prior to saving it:
C_BLOB($blob)
$err:=SR_SetPtrProperty ($report;1;SRP_Report_PageFormat;->$blob) // Mac
$err:=SR_SetPtrProperty ($report;1;SRP_Report_PrintSettings;->$blob)
$err:=SR_SetPtrProperty ($report;1;SRP_Report_DevMode;->$blob) // Win
$err:=SR_SetPtrProperty ($report;1;SRP_Report_DeviceNames;->$blob)
Value longint
Example 2
Use PDF for preview, don't embed fonts
SR_SetLongProperty (0; 0; SRP_Area_WinPreviewFlags; SRP_Print_WinPDFPreview | SRP_Print_
WinPDFNoFonts)
Example 4
Create an OXPS preview on Win8 and open after creation.
SR_SetLongProperty (0; 0; SRP_Area_WinPreviewFlags; SRP_Print_WinOpenPreview)
SR_SetTextProperty (0; 0; SRP_Area_WinPreviewName; "MyGreatestAppPreview.oxps")
Value real
Value text
Set one text property of an object. Use ReportRef = 0 and Ref = 0 to access a global
plugin property (such as SRP_Area_TraceOnError)
Example
Set the report's page margins to 12.5 on all sides:
SR_SetTextProperty ($report;1;SRP_Report_Margins;"12.5;12.5;12.5;12.5")
66 Commands by Theme
ExamplesSR_ChangeObjectParent - SR_DeleteObject
Objects
SuperReport Pro 3 uses a real object hierarchy - the objects are contained in the section/
group. When you programmatically change position, it will not move to different parent.
An object's position is relative to the parent, so when you change an object's parent, the
relative position will be the same.
Example
$err:=SR_ChangeObjectParent($report;0;$parent)
67 Commands by Theme
ExamplesSR_NewObject - SR_NewObjectFromXML
Parent text For 'normal' objects (not guide, style, section) a parent
must be provided (section or group) in Parent.
Create a new object from an XML snippet within the given parent. You can create an
object's XML programmatically and then use it to create a new object. It can be any
kind of object except the report itself. The result is the same as creating an object using
SR_NewObject and then setting all the needed properties.
68 Commands by Theme
ExamplesSR_FindObjectByID - SR_GetParent
Example
The creation of styles in the Creating Reports Procedurally example could be rewritten this
way:
$xml:="<Style id=1 name=Headers font=Helvetica size=8 qdStyle=1 wrap=1 lineSpacing=1/>"
$err:=SR_NewObjectFromXML ($rep;$newObjectID;$xml;0) // create style 1
$xml:="<Style id=2 name=Headers font=Helvetica size=8 wrap=1 lineSpacing=1/>"
$err:=SR_NewObjectFromXML ($rep;$newObjectID;$xml;0) // create style 2
NOTE: the above XML is not strictly valid - attributes have to use the syntax attribute="value"
or attribute='value'
SuperReport Pro supports omission of quotes but multi-word values must be quoted.
Ref longint
Return (in Ref) the first object in a report having SRP_Object_ID equal to Name. The comparison
is strictly equal: it is case- and diacritical-sensitive.
Example
C_LONGINT($ObjectRef)
$err:=SR_FindObjectByID($Report;"Header";$ObjectRef)
69 Commands by Theme
ExamplesSR_OpenSession
Printing
DstPath text
JobName text
Printer
Start a new printing session. Sessions are a way to print multiple reports as one print job.
When printing on Windows using SRP_Print_DestinationPreview, and the option contains SRP_
Print_WinOpenPreview, OPEN WEB URL is used on the destination file ("SRP_Preview.xps"
in User's Documents if no name was provided).
Example
Print reports of your top 20 customers and your top 50 customers as one print job:
$dest:=SRP_Print_AskPageSetup
$err:=SR_OpenSession ($session;$dest;"";[Reports]RM_ReportData;"Top customers";"LaserJet")
QUERY([Reports];[RM_Reports]RM_ReportName="Top 20 Customers")
$err:=SR_Print ([Reports]RM_ReportData;0;0;"";$session)
QUERY([Reports];[Reports]RM_ReportName="Top 50 Customers")
$err:=SR_Print([Reports]RM_ReportData;0;0;"";$session)
$err:=SR_CloseSession ($session)
70 Commands by Theme
ExamplesSR_OpenSessionBLOB - SR_CloseSession
DstPath text
JobName text
Printer
Start a new printing session and send the result to the BLoB specififed in DstPath. Sessions
are a way to print multiple reports as one print job.
71 Commands by Theme
ExamplesSR_Export
Export SuperReport Pro report without requiring a SuperReport Pro area - the output
written to the specified document is an ASCII interpretation of the report.
NOTE: The Header and Footer sections are only printed once as the report is generated
since the concept of pages don’t existing when writing the report to a document.
72 Commands by Theme
ExamplesSR_ExportBLOBIntoBLOB - SR_ExportIntoBLOB
Examples
Example 1 - Export the Body section of a report to an XML file:
$SR_Err:=SR_Export ($report;SRP_Export_XML;SRP_Export_Body;"Macintosh Disk:ProjectFolder:
Report:MyReport.xml")
This is exactly the same as SR_Export, except that both the source and the destination
are BLoBs.
This is exactly the same as SR_Export, except that the destination is a BLoB instead of
a file.
Example
Export a report into a BLoB as HTML.
C_BLOB($Blob)
SET BLOB SIZE($Blob;0)
$flags:=SRP_Export_HTML
SR_ExportIntoBLOB ([Report]ReportData;$flags;$Blob)
73 Commands by Theme
Examples SR_Print
Session longint If Session is not null, it will be used for printing and
DstFlags/inDstPath/inPrinter will be ignored (and
PageSetup/JobSetup in source will be ignored).
Printer text
Error code longint -205: Header/Footer section does not fit on a page.
-206: object does not fit into section/group (probably is
outside the bounds of a fixedheight section/group)
-207: object does not fit into fixed-size group (outside
the bounds of a group)
-210: Header section does not fit on a page
-211: section does not fit on a page
-212: too many sub-pages (horizontal splitting of a
Table object)
-213: too many pages (probably requesting a new page
infinitely)
-214: section does not fit on a new page
74 Commands by Theme
ExamplesSR_PrintBLOB
Example
You can use SR_Print to create a PDF directly (on both platforms):
$SR_Err:=SR_Print ($report;0;SRP_Print_DestinationPDF;"Macintosh Disk:ProjectFolder:
Report:MyReport.pdf";0;"")
Session longint If Session is not null, it will be used for printing and
inDstFlags/inDstPath/inPrinter will be ignored (and
PageSetup/JobSetup in source will be ignored).
Printer text
75 Commands by Theme
ExamplesSR_PrintSettings - SR_PrintIntoPICT
* Use only the report size, orientation and scaling stored in the report, not platform-native
page setup/job setup.
76 Commands by Theme
ExamplesSR_PrintBLOBIntoPICT
DstFlags Longint See SRP Print Flags - but the destination is ignored -
only the PageSetup bits are usable.
DSTArray Array The array should be initialised as ARRAY PICTURE; If the
Picture array is not empty, the pictures will be added.
DSTFormat Longint 0 - default - vector graphics (SRP_PrintPict_PDFVector
- PDF on Mac, SRP_PrintPict_EMFVector - EMF on
Windows)
1 - SRP_PrintPict_PNG
2 - SRP_PrintPict_TIFF
3 - SRP_PrintPict_JPEG
4 - SRP_PrintPict_BMP
5 - SRP_PrintPict_GIF
6 - SRP_PrintPict_PDFBitmap (on Mac)
77 Commands by Theme
ExamplesSR_ExecuteScript - SR_Area_SaveUndo - SR_Area_AddUndo
Miscellaneous
Set a flag to execute the object script at the next idle event.
Example
$err:=SR_ExecuteScript($report)
SuperReport Pro contains unlimited undo support. The plugin records all user actions and
inserts them into the undo stack. Changes executed to the report through code must be
inserted into the undo stack explicitly with the SR_Area_SaveUndo command.
The Operation parameter is used for naming Undo/Redo menu items. Internally, menu
command IDs are used, e.g. 219 = Group objects.
Example
// start recording actions
$Err:=SR_Area_SaveUndo ($ReportRef;1)
// execute any commands
// ...
// stop recording and save actions to undo stack
$Err:=SR_Area_SaveUndo($ReportRef;0)
This command is for "batch" manipulation - save the old state ("snapshot" - actually
full XML of that object), pause undo recording, modify many properties, resume undo
recording, add a "snapshot" of the new state.
78 Commands by Theme
ExamplesSR_Area_Undo - SR_Area_Redo - SR_ColorPicker
$color:=-65536
$err:=SR_ColorPicker($color;0)
79 Commands by Theme
Examples SR_DetokenizeScript - SR_RunScript - SR_RunTokenizedScript
Example 3 - use the 4D form color picker, return the mixed value
$color:=0x80FF0000 // 50% transparent red
$mixed:=1
$err:=SR_ColorPicker($color;$mixed)
Assuming the user didn't change anything and clicked OK, $err=1 and $mixed=0xFF7F0000.
or:
$color:=0x80FF0000 // 50% transparent red
$mixed:=2
$err:=SR_ColorPicker($color;$mixed) // return the mixed value
SR_RunScript (Text:T)
Parameter Type Description
Text text Script to execute.
Execute the script in "Text". The script can contain control structures. If you're familiar
with the Footrunner plugin from Footprints, this command functions in very much the
same way.
Example
Load a saved script from a record and execute it:
$Script:=[Scripts]ScriptData
SR_RunScript ($Script)
SR_RunTokenizedScript (BLOB:O)
Parameter Type Description
BLoB BLoB Tokenized script to execute.
80 Commands by Theme
ExamplesSR_TokenizeScript
Tokenize the script in "Text" and save it into a BLoB. If you need to create a long or
complex script, you can create it in 4D, tokenize it, and save it. You can then use
DOCUMENT TO BLOB with SR_GetTextProperty (0;0;"patR")+"(name)" and run it
with SR_RunTokenizedScript.
81 Commands by Theme
Properties by Theme
Properties by Theme
In this section you’ll find complete details about each property that can be used with the
SuperReport Pro commands. They are organised into themes according to which group of
commands they relate to:
Area/Plugin/Event Properties
Area Properties
Plugin Properties
Event Properties
Report Properties
Objects
Object Properties
Group Properties
Line Properties
Oval Properties
Rectangle Properties
Picture Properties
Text Properties
Text Style Properties
Variable Properties
Variable Style Properties
Field Properties
Field Style Properties
Table Properties
Header Properties
Header Style Properties
Column Properties
Column Style Properties
Section
Section Properties
Header/Footer Properties
Section Break Properties
Watermark Properties
Guide Properties
Style Properties
Data Source Properties
83 Properties by Theme
Properties by Theme
Per: Persistent. If a property is persistent, it means that the property is saved with the
area definition and will be applied when the area is displayed again.
Type: the type of the value:
Bool: boolean value (True=1 or False=0)
Longint: a long integer
Real: a real number
Text: an alphanumeric
Color: the “Color” type will accept six methods, whether as string variables or
longint variables. See Working with colors in the User Guide.
Default: the default value that will be used for this property unless you specify otherwise
Min: the minimum acceptable value, where appropriate
Max: the maximum acceptable value, where appropriate
Comments: a description of the constant and, where appropriate, a list of allowable
options
84 Properties by Theme
Area/Plugin/Event Properties
Area/Plugin/Event Properties
Area Properties
85 Properties by Theme
Area/Plugin/Event Properties
Plugin Properties
86 Properties by Theme
Area/Plugin/Event Properties
87 Properties by Theme
Area/Plugin/Event Properties
Note: When
SRP_Print_WinOpenPreview is
specified and the "Microsoft XPS
Document Writer" printer is set to
open the file after printing, it will
open twice
88 Properties by Theme
Area/Plugin/Event Properties
Event Properties
89 Properties by Theme
Report Properties
Report Properties
90 Properties by Theme
Report Properties
91 Properties by Theme
Report Properties
92 Properties by Theme
Report Properties
93 Properties by Theme
Objects
Objects
Object Properties
SRP_Object_Align is a common
object property: every leaf object
(except table header and table
column) in a section can be
positioned on the left, in the middle
or on the right
This is usable when physical paper is
used (SRP_Report_PhysicalPaper) - it
takes care of margins
Or when printable area is used -
align right will be at the right margin
94 Properties by Theme
Objects
Group Properties
95 Properties by Theme
Objects
Line Properties
Oval Properties
Rectangle Properties
96 Properties by Theme
Objects
Picture Properties
97 Properties by Theme
Objects
Text Properties
SRP_Text_Fill bool no
98 Properties by Theme
Objects
99 Properties by Theme
Objects
Variable Properties
SRP_Variable_Fill bool no
Field Properties
SRP_Variable_Fill bool no
SRP_Field_HTMLSuffix text
Table
Table Properties
SRP_Table_ int 0 = no
DrawColumns 1 = yes
2 = draw nothing (no headers) if
there are no data
SRP_Table_HTMLSuffix text
Header Properties
Column Properties
SRP_Column_Format text
Section
Section Properties
SRP_Section_ text
HTMLPrefix
SRP_Section_ text
HTMLSuffix
SRP_Section_ bool no
KeepTogether
SRP_Section_Locked int 0 0 2 Section is locked
Header/Footer Properties
Note: You can have 3 separate headers/footers, each specifying only one of the three
options - then you have separate first page header, last page header, header printed on
other pages.
Watermark Properties
Guide Properties
Style Properties
SRP_Style_Name text
SRP_DataSource_ int 1 1
Iterations
SRP_Object_XML
Appendixes
Appendix 1: Troubleshooting
Localised Formats
When the database is set to use ',' and '.' as placeholders, you must not use localized
formats (in other words always use "###,##0.00"), otherwise you must use localized
formats - e.g. "### ##0,00" on some European systems.
118
Appendix 2: Frequently Asked Questions
Q. Can I use the Repeating Objects feature for multi-level relationships? For example, if
I have a Customer, Invoice, and Line Item table, can I use repeating objects to show
all the related Invoices, and show their related Line Items?
A. No, the Repeating Objects feature is designed to work with a single related many
table. In order to create this type of report, you are going to have to create it based
on the Line Item’s table, and using Subheader data, you can show the related one
and its associated related on information. You can use a table object which supports
1->M->M->M->M relations.
Q. Why does the Debugger window sometimes open when I'm executing a SuperReport
Pro script?
A. If an error is encountered whilst a SuperReport Pro script is executing, and
SRP_Area_TraceOnError has been set to True, the 4D debugger window will open. To
turn Trace on error on:
SR_SetLongProperty ($SR_AREA;1;SRP_Area_TraceOnError;1)
To turn it off:
SR_SetLongProperty ($SR_AREA;1;SRP_Area_TraceOnError;0)
Note: This is only relevant for commands that do not return an error code.
119
Appendix 2: Frequently Asked Questions
Q. Is there any option to control the size of printed reports when using the PDF destination
for output on Windows?
A. The only option is to not embed fonts (SRP_Print_WinPDFNoFonts).
Text: all used fonts are embedded
E.g. using 2 fonts (Arial and Times New Roman) in a small 2-page report:
- 254 KB without the fonts (still too much - re-saving it using some PDF software produces
93 KB)
- 2.4 MB with the fonts (re-saving it using some PDF software produces 2.3 MB)
Images: Graphics are not down-scaled (e.g. printing 1200 dpi picture is included as-is - it
is not down-scaled to 300 or 600 dpi)
Suggestion: use PDFCreator!
SuperReportPro now supports PDFCreator directly ("print to file" using PDFCreator produces
a PS file; after creation SuperReportPro calls PDFCreator to convert it to a PDF file).
Here is an example of printing to a PDF using PDFCreator:
Q. Is there a way to set the name of the report when doing a preview?
A. The default job name is the report name - SRP_Report_Name (Edit -> Report Options
--> Name).
If it is empty, "SuperReport Pro" is used.
If you want to change the name of the Preview file on Windows, change
SRP_Area_WinPreviewName; the default is "SRP_Preview.xps" in the user's Documents
directory.
Q. Does SuperReport Pro use a virtual structure, if it has been defined, to look up 4D
fields?
A. Yes. If a virtual structure is in effect and a field is not defined in the virtual structure,
the physical field name is used.
120
Appendix 2: Frequently Asked Questions
Q. Which header and footer will be printed if the report has only one page?
A. This depends on the SRP_Section_FirstPage, SRP_Section_SecondPage and
SRP_Section_LastPage properties:
• The first header/footer having both SRP_Section_FirstPage and
SRP_Section_LastPage set to 1
• The first header/footer having one of SRP_Section_FirstPage and
SRP_Section_LastPage set to 1 and SRP_Section_SecondPage set to 0
When multiple pages are to be printed, the behavior is as follows:
• For the first page, the first header/footer having SRP_Section_FirstPage set to 1
• For the last page, the first header/footer having SRP_Section_LastPage set to 1
• For other pages, the first header/footer having SRP_Section_SecondPage set to
1
For new menu items (w/o a new constant), consult the SRProMenus.xml in the bundle.
When the property SRP_Area_CallbackVersion is set to 1:
• The menu event callback will expect a return value when called with
SR Menu Item Selected Before
• --> add C_LONGINT ($0) and set it to 1 if SuperReport Pro should handle the
menu item
• The menu item callback will be provided with 2 arguments: area and menu ID
• --> add C_LONGINT ($1; $2)
121
Appendix 2: Frequently Asked Questions
Q. Is it possible to intercept SuperReport Pro menu calls via a callback method and
let or not SuperReport Pro execute the appropriate command depending on the
programmer's choice ($0 of the callback method)?
A. No.
• The user chooses a menu item
• If a menu event callback is defined, it is called with SR Menu Item Selected Before
and menu ID
• If a command is set for the menu item, it is executed, otherwise the standard
action is taken
• If a menu event callback is defined, it is called with SR Menu Item Selected After
and the menu ID
To disable standard execution, make the respective menu item disabled...
NOTE: the menu item method gets no parameters (for compatibility), but to provide it
with areaID and menuID is possible (can be made optional - call with arguments or not).
122
Appendix 3: Hints and Tips
Printing
Due the large number of print drivers available, configuring reports for most printers can
be a very difficult task. Following is a list of some tips which can make designing your
reports a manageable job.
1. Try to leave at least 1/4” margin on the edges of your reports to account for a
wide variety of print drivers
2. Stick with common fonts.
3. Be careful of using enhanced font formatting attributes such as Bold, Italic,
Underline, etc. While most print drivers can handle multiple styles for a single
object, some print drivers have problems dealing with multiple styles.
4. Test, test, test! Try to test your reports on as many different printers as possible…
you would be surprised at the differences between drivers.
Section Markers
If you hold down the Shift key while moving a SuperReport Pro section marker, all section
markers under the selected marker will move accordingly.
SuperReport Pro 2 used only "lines" to define the start of a new section (similar to 4D form
editor).
SuperReport Pro 3 always moves all sections, because the sections are containers of
objects and one of them is being resized - all other (not selected) sections are moved.
When moving a section label, hold down the Option key to move only the label horizontally
(not to resize the section); hold down the Shift key to resize the section (not to move the
label horizontally).
Windows Preview
If a printer named "Microsoft XPS Document Writer" does not exist, Preview will not work.
You can check PRINTER LIST to find out it is present and then either install it or disable
Preview.
On Win XP SP3 "Microsoft XPS Document Writer" is present, but instead of XPS Viewer
Internet Explorer is used.
123
Index
Index
Symbols F
4D Server.............................................. 20 Field Properties..................................... 102
%SuperReport........................................ 56 Field Style Properties............................. 103
.xps...................................................... 88 filters.................................................... 13
fonts..................................................... 13
A footers................................................... 12
Adjust Object Size by Style....................... 12 functions................................................ 30
ALP_Area_SRPTableTemplate.................... 47
G
AL_Register............................................ 12
AL_SuperReport................................ 47, 48 Getters.................................................. 60
API.......................................................... 9 Getters and Setters................................. 31
appearance.............................................. 9 Group object.......................................... 12
AreaList Pro............................................ 47 Group Properties..................................... 95
Area Properties....................................... 85 Guide Properties................................... 113
B H
Boolean properties.................................. 10 Header/Footer Properties....................... 111
Boolean values....................................... 29 Header Properties................................. 105
Break Properties................................... 112 headers................................................. 12
Header Style Properties.......................... 106
C HTML export........................................... 41
Column Properties................................. 108 HTML Reports......................................... 39
Column Style Properties......................... 109
I
Compatibility............................................ 8
Compatibility Mode.................................... 9 internal variables.................................... 15
Count Pages........................................... 12
L
D
Licence, registering................................. 16
Data Source Properties................... 114, 115 License types.......................................... 22
Debugger........................................ 31, 119 Line Properties........................................ 96
Double Quotes...................................... 123 Localised Formats................................. 118
Dynamic Text.......................................... 12 local variables......................................... 13
E M
Event Cycle............................................ 36 Merged.................................................. 20
Event Properties...................................... 89 Multi-style (attributed) text...................... 13
Events (constants).................................. 89
Export to HTML....................................... 39
N
Native drawing of Text............................. 13
O
Object Properties.................................... 94
Objects............................................ 67, 94
Object Scripts......................................... 34
On Load................................................. 30
125
Index
126
Index
SR_SetProperties.............................. 62, 65 U
SR_SetPtrProperty.................................. 65
SR_SetRealProperty................................ 66 Undo buffer.......................................... 120
SR Set Script Callback......................... 9, 11 Unicode................................................. 13
SR_SetTextProperty........................... 42, 66 V
SRTime.................................................. 15
SR_TokenizeScript................................... 81 Variable Properties................................ 100
styled text.............................................. 13 Variables
Style Properties.................................... 114 39
Style Tags.............................................. 50 Variable Style Properties........................ 101
support.................................................... 8 Virtual structure.................................... 120
T W
127