FastReport.Net ProgrammerManual-en

© 2010 Fast Reports Inc. FastReport.Net Programmer's manual 3Table of contents Table of contents Chapter I General information 6 6Installing into VS Toolbox 6Troubleshooting 7Deployment 7Compiling the source code Chapter II Working with Windows.Forms 10 10Using the Report component in Visual Studio 11Working with report in a code 12Storing and loading a report 13Registering data 14Passing a value to a report parameter 14Running a report 15Designing a report 15Exporting a report 16Configuring the FastReport.Net environment 18Replacing the "Open" and "Save" dialogs 19Replacing the standard progress window 20Passing own connection string 21Passing custom SQL 21Reference to a report object 21Creating a report by using code 24Using own preview window 24Filtering tables in the Data Wizard Chapter III Working with ASP.NET 26 26Using the WebReport component 27Storing and loading a report 28Registering data 28Passing a value to a report parameter 29Working in the "Medium Trust" mode Chapter I General information 6 General information General information Installing into VS Toolbox The FastReport.Net installation program automatically adds FastReport components into the Visual Studio Toolbox. If you have disabled this feature when installing, you may add the components manually. To do this: · delete the "FastReport.Net" tab from the Toolbox, if it is there; · create a new tab (to do this, right-click the Toolbox and select "Add Tab" item), or select an existing tab you would like to add FastReport components to; · right-click on a tab and select "Choose Items...": · in the dialog, press the "Browse..." button and choose FastReport.dll, FastReport.Web.dll files (they are located in the "C:\Program Files\FastReports\FastReport.Net" folder); · close the dialog with OK button. After this, you will see FastReport.Net components in a chosen tab: · Report; · PreviewControl; · DesignerControl; · EnvironmentSettings; · WebReport (this component will be visible in ASP.NET project only). Troubleshooting If you face a problem when working with report designer (for example, some toolbars or tool windows are damaged), you should delete the configuration file. This file is created when you start FastReport.Net. It is located in the following folder: Windows XP: C:\Documents and Settings\user_name\Local Settings\Application Data\FastReport\FastReport.config 7General information Windows Vista: C:\Users\user_name\AppData\Local\FastReport\FastReport.config The following information is stored in the config: · sizes and locations of dialog windows; · toolbar settings; · recent used data connections; · email settings (if you use the "Send Email" feature in the preview). Deployment You may redistribute the following files along with your application: · FastReport.dll - the main FastReport.Net library; · FastReport.Web.dll - the library that contains ASP.Net WebReport component; · FastReport.Bars.dll - the toolbars and docking windows library; · FastReport.Editor.dll - the code editor with syntax highlight. This library is not needed if you don't provide an end-user designer; · FastReport.xml - comments for classes, properties and methods used in FastReport. This file is used by the script editor, and also by the hint panels in the "Data" and "Properties" windows. It's not obligatory to distribute this file. You may distribute the User's Manual which is contained in the FRNetUserManual.chm file. This file can be shown from the report designer, if you select the "Help|Contents..." menu item. If your reports are stored in files, you have to deploy them as well. Compiling the source code Source code is shipped with FastReport.Net Professional edition. It includes source code of FastReport.dll, FastReport.Web.dll libraries. You may include it in your application's solution file. Let us demonstrate how to do this: · open your project in the Visual Studio; · open the Solution Explorer and right-click on the "Solution" item; · choose the "Add/Existing Project..." item; · add the "FastReport.csproj" file (it is located in the "C:\Program Files\FastReports\FastReport.Net\Source\FastReport" folder); · add the "FastReport.Web.csproj" file (it is located in the "C:\Program Files\FastReports\FastReport.Net\Source\FastReport.Web" folder). Turn off assembly signing for FastReport and FastReport.Web projects. To do this: · right-click the "FastReport" project in the Solution Explorer; · choose the "Properties" item; · switch to the "Signing" tab and uncheck the "Sign the assembly" checkbox; · do the same steps for FastReport.Web project. Update the references to other FastReport.Net assemblies. To do this: · expand the "FastReport\References" item in the Solution Explorer; 8 General information · remove the "FastReport.Bars", "FastReport.Editor" references; · right-click the "References" item and choose the "Add Reference..." item; · add references to the "FastReport.Bars.dll", "FastReport.Editor.dll" and "System.Windows. Forms.DataVisualization.dll" files. These files are located in the "C:\Program Files\FastReports\FastReport.Net" folder. Chapter II Working with Windows.Forms 10 Working with Windows.Forms Working with Windows.Forms Using the Report component in Visual Studio Let us consider the typical use of the Report component in Visual Studio. We will use the data from a typed dataset. · create a new Windows Forms application; · add a dataset into it ("Data|Add New Data Source..." menu item); · switch to the Form designer; · add the "DataSet" component on a form and connect it to the typed dataset that you have created. To create a report, perform the following steps: · put the "Report" component on a form: · right-click it (or click on a smart tag button) and select the "Design Report..." item: · choose the data source to use in a report: 11Working with Windows.Forms · create your report. Read more about this in the User's Manual; · close the report designer; · add a "Button" control on your form; · double-click it and write the following code in the button_Click event handler: report1.Show(); · save the project and run it. When you click on a button you will see the prepared report. Working with report in a code To work with Report component in a code, you need to do the following: · create a report instance; · load a report file into it; · register the application-defined data in a report; · pass the values into the report parameters, if needed; · run the report. The following example demonstrates how to do this: using (Report report = new Report()) { report.Load("report1.frx"); report.RegisterData(dataSet1, "NorthWind"); report.Show(); } We will consider these steps in details in the following sections of this manual. 12 Working with Windows.Forms Storing and loading a report You may store a report in the following ways: Method Description in the application's resources The typical scenario of using the Report, which we looked at before, uses this method. The StoreInResources property of the Report object is responsible for this. This property is set to true by default. This method has the following pros and cons: + a report is embedded into your application, you don't need to deploy extra files; - if you need to change a report, you have to recompile your application. Loading a report is performed automatically. To do this, FastReport.Net adds a code into the InitializeComponent method of your form. in the .FRX file This method is useful if you want to give your users the ability to change a report. In this case, set the report's StoreInResources property to false. To load the report from a file, use the Load method of the Report object: report1.Load("filename.frx"); in the database You may store a report in the database, either as a string or in a blob- stream. To load the report from a string, use the LoadFromString method of the Report object. To load the report from a stream, use the overloaded version of the Load method: report1.Load(stream); To support the load/save operations in the report designer, you need to replace the "Open File" and "Save File" dialogs in the designer. Read here how to do this. as a C#/VB. NET class To work with a report as a class, design your report and save in to the .cs/. vb file. To do this, select "file type" in the "Save" dialog. The file type maybe either .cs or .vb - it depends on the script language in the report (it may be changed in the "Report|Options..." menu). Include that file into your project. This method has the following pros and cons: + you can work with a report as a class; + you may debug a report; + this is the only way to use a report in ASP.NET project running on medium trust environment; - you cannot edit such a report. To do this, you need the original .FRX file; - if you need to change a report, you have to recompile your application. To work with a report, create an instance of the report's class: SimpleListReport report = new SimpleListReport(); report.Show(); 13Working with Windows.Forms Registering data If your report uses data from an application (for example, the typed dataset or a business- object), you have to register such data in a report. This can be done using the RegisterData method of the Report object. When you use the Report as described in the "Using the Report component in Visual Studio" section, you don't need to register the data. FastReport.Net does it automatically (it adds the RegisterData call in the InitializeComponent method of your form). The RegisterData method must be called after you have loaded the report: report1 = new Report(); report1.Load("report.frx"); report1.RegisterData(dataSet1, "NorthWind"); The RegisterData method is overloaded and allows to register the following data: Method Description void RegisterData( DataSet data) Registers the dataset. This method registers all tables, viewsand relations as well. Attention: if you register more than one dataset, use the RegisterData(DataSet data, string name) method instead. void RegisterData( DataSet data, string name) Registers the dataset. Specify any name in the name parameter (it must be persistent and unique if you register more than one dataset). void RegisterData( DataTable data, string name) Registers the data table. void RegisterData( DataView data, string name) Registers the data view. void RegisterDataAsp( IDataSource data, string name) Registers the ASP.NET data source such as AccessDataSource. void RegisterData( DataRelation data, string name) Registers the relation. void RegisterData( IEnumerable data, string name, BOConverterFlags flags, int maxNestingLevel) Registers the business object. Specify what items (properties, fields) should be used, in the flags parameter. Specify the maximum nesting level in the maxNestingLevel parameter (typically you need no more than 3 levels). Several nested objects may slow down the report. 14 Working with Windows.Forms Passing a value to a report parameter The report may have parameters. Read more about this in the User's Manual. To pass a value to the parameter, use the SetParameterValue method of the Report object: report1.Load("report.frx"); report1.SetParameterValue("MyParam", 10); report1.Show(); This method is declared as follows: public void SetParameterValue(string complexName, object value) Specify the parameter's name in the complexName parameter. To access a nested parameter, use its full name, for example: "ParentParameter.ChildParameter" Running a report To run a report, use one of the following methods of the Report object: Method Description void Show() Runs a report and shows it in the preview window. This method is equal to: if (Prepare()) ShowPrepared(); bool Prepare() Runs a report. If the report was prepared successfully, returns true. After this method, you need to call one of the following methods: ShowPrepared, PrintPrepared, SavePrepared, Export: if (Prepare()) ShowPrepared(); bool Prepare( bool append) Runs a report. If the append parameter is set to true, the preparedreport will be added to the existing one. So you can build several reports and display them in the preview as one report: report1.Load("report1.frx"); report1.Prepare(); report1.Load("report2.frx"); report1.Prepare(true); report.ShowPrepared(); void ShowPrepared()Shows a prepared report in the preview window. The report must be either prepared using the Prepare method, or loaded from the .FPX file using the LoadPrepared method: if (Prepare()) ShowPrepared(); 15Working with Windows.Forms void ShowPrepared( bool modal) Shows a prepared report in the preview window. The modal parameterdetermines whether the preview should be shown modally. void ShowPrepared( bool modal, Form owner) The same as the previous method. The owner parameter determines a window that owns the preview window. void ShowPrepared( Form mdiParent) The same as the previous method. The mdiParent parameterdetermines the main MDI window. Designing a report You can use the report designer in your application. This is possible for all FastReport.Net editions except the Basic. To do this, use the Design method of Report object: report1 = new Report(); report1.Load("report1.frx"); report1.Design(); The Design method is overloaded: Method Description bool Design() Shows the designer. bool Design( bool modal) Shows the designer. The modal parameter determines whether it isnecessary to show the designer modally. bool Design( Form mdiParent)Shows the designer. The mdiParent parameter defines the main MDIwindow. Exporting a report The prepared report can be exported to one of the supported formats. At this moment, the following formats can be used: · PDF · HTML · RTF · Excel XML (Excel 2003+) · Excel 2007 · CSV · TXT · OpenOffice Calc · Pictures (Bmp, Png, Jpeg, Gif, Tiff, Metafile) The export is performed by the export filter. To do this: · prepare a report using the Prepare method; · create an instance of export filter and set up its properties; 16 Working with Windows.Forms · call the Export method of the Report object. The following example exports a prepared report in the HTML format: // prepare a report report1.Prepare(); // create an instance of HTML export filter FastReport.Export.Html.HTMLExport export = new FastReport.Export.Html.HTMLExport(); // show the export options dialog and do the export if (export.ShowDialog()) report1.Export(export, "result.html"); In this example, export settings are made using the dialog window. Configuring the FastReport.Net environment Using the EnvironmentSettings component which is available in the Toolbox, you can control some FastReport.Net environment settings. To do this, put the component on your form and set up its properties using the Properties window. The EnvironmentSettings.ReportSettings property contains some report-related settings: Property Description Language DefaultLanguageThe default script language for new reports. bool ShowProgress Determines whether it is necessary to show the progress window. bool ShowPerformance Determines whether to show the information about the report performance (report generation time, memory consumed) in the lower right corner of the preview window. The EnvironmentSettings.DesignerSettings property contains some designer-related settings: Property Description Icon Icon The icon for the designer window. Font DefaultFont The default font used in a report. The EnvironmentSettings.PreviewSettings property contains some preview-related settings: Property Description PreviewButtons ButtonsSet of buttons that will be visible in the preview's toolbar. int PagesInCache The number of prepared pages that can be stored in the memory cache during preview. bool ShowInTaskbar Determines whether the preview window is displayed in the Windows taskbar. bool TopMost Determines whether the preview window should be displayed as a topmost form. 17Working with Windows.Forms Icon Icon The icon for the preview window. string Text The text for the preview window. If no text is set, the default text "Preview" will be used. The EnvironmentSettings.EmailSettings property contains email account settings. These settings are used in the "Send Email" feature in the preview window: Property Description string Address Sender address (e.g. your email address). string Name Sender name (e.g. your name). string MessageTemplateThe message template that will be used to create a new message. For example, "Hello, Best regards, ...". string Host SMTP host address. int Port SMTP port (25 by default). string UserName, string Password User name and password. Leave these properties empty if yourserver does not require authentication. bool AllowUI Allows to change these settings in the "Send Email" dialog. Settings will be stored in the FastReport.Net configuration file. UI style settings are available in the following properties of EnvironmentSettings component: Property Description UIStyle UIStyle The style of designer and preview form. 6 styles are available - VisualStudio2005, Office2003, Office2007Blue, Office2007Silver, Office2007Black, VistaGlass. The default style is Office2007Black. bool UseOffice2007FormThis property affects the designer and preview form. It determines whether the Office2007-style form should be used if one of the following styles is selected: Office2007Blue, Office2007Silver, Office2007Black, VistaGlass. Default value is true. Besides these properties, the EnvironmentSettings component has some events. Using such events, you may do the following: · replace standard "Open file" and "Save file" dialogs in the designer; · replace standard progress window; · pass own connection string to a connection defined in the report. These tasks will be described in the following sections of this manual. 18 Working with Windows.Forms Replacing the "Open" and "Save" dialogs If you decided to store a report in the database, you may need to change the designer in such a way that it can open and save reports from/to a database. That is, you need to replace standard "Open" and "Save" dialogs with your own dialogs that work with database. To do this, use the EnvironmentSettings component (see the previous section). This component has the following events: Event Description CustomOpenDialog Occurs when the report designer is about to show the "Open" dialog. In the event handler, you must display a dialog window to allow user to choose a report file. If dialog was executed successfully, you must return e.Cancel = false and set the e.FileName to the selected file name. The following example demonstrates how to use this event: private void CustomOpenDialog_Handler( object sender, OpenSaveDialogEventArgs e) { using (OpenFileDialog dialog = new OpenFileDialog()) { dialog.Filter = "Report files (*.frx)|*.frx"; // set e.Cancel to false if dialog // was succesfully executed e.Cancel = dialog.ShowDialog() != DialogResult.OK; // set e.FileName to the selected file name e.FileName = dialog.FileName; } } CustomSaveDialog Occurs when the report designer is about to show the "Save" dialog. In the event handler, you must display a dialog window to allow user to choose a report file. If dialog was executed successfully, you must return e.Cancel = false and set the e.FileName to the selected file name. The following example demonstrates how to use this event: private void CustomSaveDialog_Handler( object sender, OpenSaveDialogEventArgs e) { using (SaveFileDialog dialog = new SaveFileDialog()) { dialog.Filter = "Report files (*.frx)|*.frx"; // get default file name from e.FileName dialog.FileName = e.FileName; // set e.Cancel to false if dialog // was succesfully executed e.Cancel = dialog.ShowDialog() !