RDC Object Model Architecture


The RDC conforms to Microsoft s COM. As such, it can be used in any COM-compatible development environment that supports a COM Library (formerly known as an OLE server ), such as Visual Basic, Visual C++, Delphi, and Microsoft Visual InterDev for web page development (web integration with the RDC is covered in Chapter 22). While an in-depth discussion of COM is better left to Microsoft documentation, you can consider COM to be a set of standards that allows one software environment to utilize the functions of another software environment by way of objects, properties, methods , and events.

COM development falls under the category of object-oriented programming (OOP). An object hierarchy is exposed by the RDC. This hierarchy begins with high-level objects that contain lower levels of objects. These second-level objects can contain lower levels of objects, and so on. If it sounds like the levels of objects can get deep, they sometimes do. Some objects in the RDC are four or five layers deep in the object hierarchy.

Objects can contain not only additional single objects below them, but also collections of objects. A collection is a group of related objects contained inside the parent object. For example, a Report object will contain a collection of Section objects (an object for the report header, page header, and so on). Each of these Section objects itself contains its own collection of Report objects, such as fields, text objects, formulas, lines, boxes, and so on. If the details section of a report has ten database fields, four formulas, and a line drawing, the Details Section object will contain an object collection consisting of 15 members ”one member for each of the Report objects in the section. And, if a report simply contains the five default sections that are created with a new report, the report s Sections collection will contain five members ”one for each section.

If you aren t using the RDC s internal ActiveX report designer but instead are integrating an external .RPT file, the highest level in the object hierarchy is the Application object ” everything eventually trickles down from it. Although you do need to declare the Application object in your VB code, you will rarely (if ever) refer to it again, or set any properties for it, once it s declared. As a general rule, the highest level of object you ll regularly be concerned with is the Report object, created by executing the Application object s OpenReport method (or automatically created if you are using the RDC s internal ActiveX designer). You will then manipulate many of the Report object s properties (such as the RecordSelectionFormula property), as well as work with many objects below the Report object (such as report sections, as just discussed).

Because the RDC is a tightly integrated COM component, you will benefit from Visual Basic s automatic code completion when you use it. When you begin to enter code into the VB code window for the Report object, the properties, methods, and built-in constant values become available to you from automatically appearing drop-down lists. If you ve used Visual Basic 5 or 6, you re probably already familiar with this feature. You ll enjoy the benefit it provides with the RDC, as well.

Whereas older Crystal Reports integration methods required you to develop the report s .RPT file in the Crystal Reports design tool and then integrate it into your VB application, the RDC gives you the choice of actually designing the report right inside VB, as well as integrating existing .RPT files. Not only will you find most of the same design capabilities available from within the RDC that are available in regular Crystal Reports, but virtually all the fields, formulas, text objects, sections, and other parts of the report will be exposed to VB as objects (but, as mentioned previously, the repository is not supported inside the VB designer). Like VB forms and controls, Report objects have properties and methods that can be set at both design time and run time. And, if you still choose to use an external .RPT file, the RDC exposes several COM interfaces, allowing sophisticated object-oriented report integration with both external .RPT files and the RDC s built-in report designer.

Note  

Even though the RDC adds the ability to create reports completely within the VB IDE, you still may prefer to design reports in the stand-alone copy of Crystal Reports. One of the immediate benefits to this is the Preview tab ”you can immediately see how your report will look when making cosmetic changes. If you use the VB Active X Report Designer and a report viewer, you ll need to rerun your application every time you want to see how your report design changes will appear.

Tip  

You can find the completed VB application on this book s companion web site. Download the application from www.CrystalBook.com.

start sidebar
The Xtreme Mountain Bike Sample Reporting Application

The sample application used in this chapter, as well as on the book's companion web site (www.CrystalBook.com), is a sample orders report for Xtreme Mountain Bike, a fictional company used throughout this book. The data for the report comes from the XTREME.MDB Microsoft Access sample database that's included with Crystal Reports 10 (connected via ODBC). The application will present a user-friendly, graphical user interface for end users who want to print an Xtreme order report.

This report contains several special features you'll want to enable for your end users in the VB application:

  • A user-specified sales-tax rate that is used in the Order + Tax formula.

  • The ability to group by calendar quarter or customer name , based on user selection.

  • A prompt for a highlight value to set orders over a certain amount apart. This value will be passed to a report parameter field.

  • An order-date range that will limit the report's record selection.

  • A label in the page header of the report indicating the choices the user has made.

  • The choice to show detail data, or to just group subtotals and summaries for drill- down. The report contains two different page header sections and two different group header sections, containing column headings that are suppressed and shown according to the summary/detail choice.

  • Destination options to preview the report in a window, print the report to a printer, or send the report as a Portable Document Format (.PDF) file, attached to an e-mail message.

    If the report is grouped by quarter, given a 5 percent tax rate, and restricted to orders from January 1 through December 31, 2001, and if the parameter field to highlight orders is given a value of $5,000, the report will appear as illustrated here:

    click to expand

    The VB application that will be used to integrate this report is a simple, single-form dialog box that gathers data from the user via text boxes, a combo box, radio buttons , and a check box. When the user clicks OK, the report is previewed, printed, or e-mailed, depending on the selections made. The main form from the application looks like this:

    click to expand

    To correctly accomplish the integration, you need to programmatically modify the following report properties from within your VB application:

  • Record selection formula

  • Report formula

  • Parameter field

  • Output destination

  • Report section formatting (suppress and show)

end sidebar
 

Different RDC Pieces

The entire RDC actually consists of several parts that work together. In particular, it has four separate pieces:

  • ActiveX designer Enables you to actually create and modify reports inside the Visual Basic IDE.

  • Run-Time Library After you create the report, the RDC exposes a set of powerful properties, methods, and events via a COM library.

  • Report Viewer Because the RDC doesn t include its own built-in preview window, you use another ActiveX component, the Report Viewer, to view reports on the screen. The Report Viewer also exposes a large set of properties, methods, and events, enabling you to have complete control over how your application users can interact with your report in the viewer window.

  • Embeddable Report Designer This feature allows you to place an ActiveX control on your VB form to allow end users to interactively design reports using features almost identical to the report designer available inside the VB IDE. Once users have finished their report design, the Embeddable Report Designer returns a report object that can be further modified and controlled with the run-time library.

The ActiveX Designer

The first part of the RDC is an ActiveX designer, an interface that works with Visual Basic 5 and 6, and Microsoft Office Developer s Edition (using VBA 6). Whereas other ActiveX controls and libraries generally extend the capabilities of the Visual Basic language, an ActiveX designer actually extends the capabilities of the Visual Basic IDE. Some common examples are the User Connection Designer and the Data Environment Designer, both of which are ActiveX designers for connecting to remote databases that are available with Visual Basic 6.

The designer portion of the RDC allows you to create a complete report right inside Visual Basic. You no longer need to use the iterative process of creating or editing a Crystal Reports .RPT file, working with it inside your VB code, going back to Crystal Reports to make changes to the .RPT file, and going back to VB to make changes in the code. The RDC looks similar to the Crystal Reports design screen, with multiple report sections, lists of database fields, formulas, parameter fields, and so on. You interact with the RDC via toolbar buttons and pop-up menus .

What the RDC designer features that Crystal Reports doesn t offer is a complete object model for every report section and every object you place in any report section. Every field, text object, formula, parameter field, or any other type of object has its own set of properties that appears in the property sheet, and many of those properties can be set at run time. With the RDC, you can customize formulas, text objects, section formatting, and most other aspects of report behavior and formatting by using VB coding. By creatively using text objects, you can even create report formulas using the Visual Basic language instead of the Crystal formula language so that the text objects will be under complete VB control at run time. Of course, any Crystal formulas you create will still work, and they can still be modified on the fly from within your application, just as with other integration methods.

The Run-Time Library

The second part of the RDC is the RDC run-time library. This component can accept either a report designed with the RDC ActiveX designer or an external .RPT file created with Crystal Reports 10. The RDC then exposes a large number of properties and methods that can be used to completely customize reporting behavior at run time.

The Report Viewer

The RDC Design Time or Run-time components don t include their own built-in preview window for previewing reports on the screen. Therefore, report previewing is provided by yet another ActiveX component that is available with the RDC, the Report Viewer. This ActiveX control is added to a form, where it exposes a large number of properties in the Properties box displayed in the VB IDE that can be set at design time. When your program is run, the viewer is supplied with a Report object from the RDC Library, which it then displays in its window according to the selections you made at design time.

Not only can many of these properties also be set at run time, but the viewer contains its own COM library, which exposes a large number of other properties, methods, and events that let you completely control report behavior and interaction. You can open drill-down tabs right from within your code, trap a button click in the viewer toolbar, or respond to a drill-down click on a group footer or header. The viewer is versatile enough that conceivably you can design your own container for the Report Viewer window, creating all of your own controls and logic for report interaction.

Tip  

The RDC s run-time library and Report Viewer also can be used to develop thin-client applications that require only a web browser. Both modules can integrate reports using Microsoft Active Server Pages. Chapter 22 provides complete details of this use of the RDC.

start sidebar
When Are Royalty Payments Required?

Crystal Reports has always maintained a tradition of a royalty-free , run-time license for developers. In the past, you could freely distribute run-time Crystal Reports modules, such as CRAXDRT.DLL (the RDC run-time library), without having to notify, or pay royalties to, Business Objects. As report integration capabilities have become more robust, however, your free distribution options have been reduced.

However, this isn't necessarily cause for concern. Quite simply, all run-time report modification functions (that make changes to existing reports, either designed in the Crystal Reports designer or VB's integral Active X designer) can still be included in your custom applications without requiring any royalty payments to Business Objects. However, functionality that allows an application to create a new report from scratch, as well as use of the Embeddable Report Designer, does require additional purchases.

However, this has been simplified with Crystal Reports 10. Previously, you needed to purchase separate distribution licenses when you distributed applications that used internal report creation features. Now, any organizations you distribute your application to must simply purchase their own copy of Crystal Reports 10 Advanced Developer Edition. No more run-time license purchases are required. Or, you may also simply purchase a copy of Crystal Reports 10 Advanced Developer Edition yourself and include it with the custom application ”as long as there is a properly purchased copy of CR 10 Advanced Developer purchased when the application is distributed, no additional licensing requirements come into play.

And, you must have your own copy of Crystal Reports 10 Advanced Developer Edition if you want to create applications that make use of the Embeddable Report Designer or run-time report creation API calls. Attempts to use this technology with Crystal Reports 10 Developer Edition (not Advanced Developer Edition) will result in trappable errors.

end sidebar
 

The Embeddable Report Designer

Not only can you modify existing reports at run time from within your code, but Crystal Reports 10 offers a fully interactive report design ActiveX control that can be added directly to a VB form. With this control, end users have full interactive capabilities to design new reports or edit existing reports from within your VB application. By providing an already defined Report object to the Embeddable Report Designer, you can allow users to modify an existing report interactively. Or, simply allow an end user to use the Embeddable Designer to create a complete report from scratch, much as you would using the RDC ActiveX designer inside the VB IDE. In either case, when the end user has completed his or her report design process, the Embeddable Report Designer simply returns another Report object that can be further manipulated before being printed, exported, or displayed in the Report Viewer.




Crystal Reports 10
Crystal Reports 10: The Complete Reference
ISBN: B005DI80VA
EAN: N/A
Year: 2004
Pages: 223
Authors: George Peck

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net