SilverStream Java-based view controls let you display data, from one or more database tables, in a tabular (row and column) format. This chapter introduces the Java-based view controls and includes these topics:
SilverStream provides these two Java-based view controls:
A class that you construct programmatically using the Form Designer's Programming Editor. | |
The class constructed by the SilverStream View Designer. AgcViewDownloadable is a subclass of AgcView. |
Views are composed of several objects that define their physical appearance. Data is provided by a separate object that is an AgiRowCursor or an AgoTreeDataManager (for hierarchical views).
SilverStream provides the column formats described in the following table:
Static and dynamic views provide a similar look and feel. Static views are easier to build and define because you can use the View Designer. However, the AgcViewDownloadable control is only appropriate in situations where the view's physical appearance and its data source are static and known at design time
Using static views
You can use static views to display derived data and aggregates. Once you have defined and saved the view using the View Designer, SilverStream makes it available to the Form and Page Designer environments, and you can drag it directly onto a page or form. This is extremely useful for defining Master/Detail data formats. Once you have placed it on a form or page, SilverStream handles all of the view's instantiation and initialization using the metadata that is stored on the server. The metadata is created automatically at design time and specifies both the physical appearance of the view as well as its data binding.
You must programmatically navigate and manipulate the view control at runtime, but do not have to programmatically manage the data binding or loading.
See the View Designer section of the help system for information about creating an AgcViewDownloadable control.
Using dynamic views
The AgcView API exposes the SilverStream objects that the View Designer uses when it generates a static view. For example, when you use the View Designer to specify a background color, SilverStream calls the setBackgroundColor() method on the appropriate object to make it happen.
Like the static view, the dynamic view lets you display and manipulate the results of a simple single-table query or a complex multi-table query in a tabular format. It might be more time-consuming to create, but it provides additional functionality and flexibility. For example, you can:
Use the guidelines in the following table to help you choose the appropriate view control based on your application requirements
To create a dynamic view, you programmatically create each column, band and view format object in the following order:
NOTE You use the View Designer to create static views.
For more information on creating static view, see the View Designer chapter in the online Tools Guide.
To create an AgoViewFormat, use the null constructor AgoViewFormat(). This example shows how to create an AgoViewFormat (called vfmt), set its background color to white, and its caret color to green.
AgoViewFormat vfmt = new AgoViewFormat();
vfmt.setBackgroundColor(Color.white);
vfmt.setCaretColor(Color.green);
To create an AgoBandFormat, use the AgoBandFormat() constructor which has the following declaration:
AgoBandFormat(String name)
The following example shows how to create two AgoBandFormats; one named dataBand, the other named headingBand.
AgoBandFormat bfmt = new AgoBandFormat("dataBand");
AgoBandFormat hdrfmt = new AgoBandFormat("headingBand");
You use the AgoBandFormat() constructor to create bands for both data bands and header bands. You specify it as a header band when adding it to the view format.
You should name a band when you create it. If you do not, SilverStream assigns it the name "unnamedx" when you add it to the view format. The x is a number that is incremented for each new unnamed band that you add.
You build a band by stringing together column formats.
Each column type has its own constructor. Some let you specify initial values, while others require that you call a separate method to initialize it.
For more information about the constructor for each of the column format types, see the online API Reference.
You can optionally set initial values for hierarchy, text, and text editor column types. The initial values include a number of commonly used attributes, such as fonts, text color, and alignment. SilverStream supplies an initialization method for columns that are part of the header band and one for columns that are part of a data band.
For columns in header bands
Header columns are not updateable. It is most common to use an image column or a text column in header bands. To initialize a text column that is part of the header band, call the initColumnTextHeader() method.
The following example illustrates how to initialize a header band column that displays the text "Customer ID", using Helvetica, plain, 12 point font. The text color for this column is black and the column text is aligned to the left.
//Instantiate a fontid for the column text
AgoFontIdentifier fontid = new AgoFontIdentifier("Helvetica", 0, 12);
//Instantiate a text column
AgoColumnText colTextHeader1;
colTextHeader1 = new AgoColumnText(100, true, false, Color.white, AgoColumnBase.BORDER_3D);
//Initialize the column header data
colTextHeader1.initColumnTextHeader("Customer ID", fontid, Color.black, AgoColumnBase.ALIGN_LEFT);
For columns in data bands
To initialize a text column that is part of a data band, call the initColumnTextProperty() method.
The following example illustrates how to initialize a data band column that is bound to the "customerid" property of the view's data source. It displays the data using Helvetica, plain, 12 point font. It displays the text in black and the text is aligned to the left of the column.
//Instantiate a fontid for the column text
AgoFontIdentifier fontid = new AgoFontIdentifier("Helvetica", 0, 12);
//Instantiate a text column
AgoColumnText colText1;
colText1 = new AgoColumnText(100, true, false, Color.white, AgoColumnBase.BORDER_3D);
//Initialize the column
colText1.initColumnTextProperty("customerid", fontid, Color.black, AgoColumnBase.ALIGN_LEFT);
If there is no customerid column defined in the view's data source (or the column name is misspelled), no data will be displayed in the column at runtime.
To add columns to a band, you call the AgoBandFormat.appendColumnFormat() method.
The following example shows how to append two columns, colText1 and colText2, to a band named bfmt.
bfmt.appendColumnFormat(colText1);
bfmt.appendColumnFormat(colText2);
The order in which you append the columns determines the column order (left-to-right) on the band.
To add bands to a view format, you call the AgoViewFormat.appendBandFormat() method. This example shows how to add a band format called bfmt.
vfmt.appendBandFormat(bfmt);
You create a header band by calling the AgoViewFormat.setHeaderBand() method.
This example shows how to set an AgoBandFormat object called hdrfmt as the header band for the view.
vfmt.setHeaderBand(hdrfmt);
There are no special requirements for specifying header bands. However, only one band can be specified as the header band. If you specify more than one header band, SilverStream uses the one that was most recently defined.
There are two ways to instantiate an AgcView:
NOTE Instantiating an AgcView does not also fill it with data. Regardless of the way that you instantiate the control, you must always call the AgcView.init() method to load data to the view.
This is the easiest way to instantiate a dynamic view. When done this way, SilverStream generates the Java method call that instantiates the control and sets the properties at runtime.
To instantiate a dynamic view using the Form Designer:
This technique is slightly more complicated than using the Form Designer; however, it can provide additional control because you write the Java code that instantiates the AgcView and sets it properties in whatever event you deem appropriate for your application. This might include the FormLoaded event or a button click.
The following example shows how to instantiate an AgcView named "myView".
AgcView myView = new AgcView();
myView.setName("custView");
myView.setBounds(11,4,466,228);
this.add(myView);
Static and dynamic views must be bound to data objects that implement the AgiRowCursor interface. The view receives data during its initialization when the AgcView.initView() method is called. The AgcView.initView() method associates the AgcView object with an AgoViewFormat object, and an AgiRowCursor.
Data binding is transparent with static views; SilverStream creates the data object and passes the data object on the initView() method automatically. For dynamic views, you must make sure the form has access to the data object and specify the data object's name in the call to initView(). Dynamic views are typically bound to AgcData controls, but you can also write your own class that provides the data.
For information on writing your own class that implements the AgiRowCursor interface, see the chapter on advanced data access.
In the View Designer, you use the Property Inspector to bind a static view to a database table. When you specify a database table, SilverStream constructs a SQL Select statement that returns all of the rows of the table, in no particular order. You can customize the SQL that SilverStream constructs at either design time or runtime.
Restricting data at design time
You can customize the Select statement at design time by specifying Where clause and Order By clause values in the Property Inspector. When specifying a Where clause, you must qualify the field name with the table name. For example, to select all of the employees that work in department 300, you would specify the following Where clause:
employees.deptid=300
Restricting data at runtime
At runtime, you can use the query() method to construct a Where and Order By clause. The fields that you name in the query string must already be referenced by the control.
SilverStream treats the query as a string; it provides no syntax checking. If the syntax for the query is not correct, the query() either returns no data, or throws an exception. To select all of the employees that work in department 300, you would specify the following Where clause:
view.query("employees.deptid=300")
If you use both the Where Clause and the query() method, SilverStream uses the SQL AND operator to append the query() method's Where clause to the Where clause specified in the Property Inspector.
Linking to other controls
You might want to display a customer's name in a text field and that customer's orders in a view. When the customer changes, the orders should also change. SilverStream provides this functionality using a Link clause. The Link clause describes a join operation between the datasets of the form and the view. You might think of it as a further refinement of the view's Where clause.
SilverStream tries to automatically generate a Link clause when you drop the view onto a form. If SilverStream cannot determine a relationship between the datasets, it does not generate a Link clause. You can add one or modify an existing one through the Link Clause property. This property is available on the View control once it is dropped on the form.
Loading data to the view
You can customize the point at which data is loaded to the view. To populate the view as soon as the form is loaded and the view is made visible, you can set the property Automatic Query to true (the checked value). If Automatic Query is false (not checked), SilverStream does not load the view until the query() or refreshRows() methods on the view are called.
Updating static views
If you allow the user to change the view's data (using Text Editor columns), you can write updates to the database by calling updateRows().
If you call updateRows() on the view, only the changes to the view are written to the database. If you call updateRows() on the form's agData, the changes on the parent form, other controls on the form, and the view itself are updated as a single transaction.
You can bind a dynamic view to any Java class that is an AgiRowCursor or an AgoTreeDataManager.
To use an AgcData control with a dynamic view:
initView() method and pass the name of the AgcData control. The following code fragment initializes the AgcView control with an AgcData control called myAgcData and an AgoViewFormat object called viewFmt.
AgcView.initView(myAgcData, viewFmt);
Registering as event listeners
When you pass an AgcData control to the initView() method, SilverStream registers the AgcData control as a listener for events on the AgcView control. For example, when the user moves the caret from one row to another, the AgcData control receives an ActionPerformed event from the AgcView control.
The initView() also registers the AgcView control as a listener for AgcData. When an event occurs on the AgcData control (that is, the cursor moves to the next row through a call to gotoNext()) the AgcView control is also notified.
Since the view's data object is an AgiRowCursor, you use the AgiRowCursor methods to navigate it. You use these methods with both static and dynamic views.
Finding the currently selected row
To find the row that the user currently has selected, you call the getSelectedRowCursor() method. For example:
AgiRowCursor curEmployees =
vwSalaryChange.getSelectedRowCursor();
The getSelectedRowCursor() returns an object of type AgiRowCursor. The AgiRowCursor points to the currently selected row or null if no row is selected. As an alternative, you can call the getRootRowCursor() method. The advantage is that it returns an AgiRowCursor even when no row is selected. Consider using getRootRowCursor() when you are inserting rows and it is possible that the view does not yet contain rows.
Navigating and manipulating datasets
You navigate and manipulate the dataset using the AgiRowCursor navigation methods such as gotoNext() and gotoPrevious(), and the AgiRowCursor data manipulation methods like insertBefore() , insertAfter(), and so on. To add a row to the root cursor, use the appendChild() method instead of the insertAfter() method.
For more information about the AgiRowCursor methods and how to use them, see the online SilverStream API.
Other data set considerations
Note that the AgiRowCursor methods manipulate the AgiRowCursor object. They do not change which row in the view is selected.
Views can also supports methods that allow you to manipulate an entire dataset by implementing the AgiRowSetManager interface.
The AgoTreeDataManager object provides support for hierarchical row cursors. AgoTreeDataManager provides an implementation of the AgiRowCursor that supports the gotoChild() method. It is based on the JDK1.2 Collection classes. It allows you to build and maintain hierarchical data views.
For more information on AgoTreeDataManager, see the SilverStream API in the online help.
Here are some tips for setting up the view and row formats if you plan on using a tree data manager with an AgcView:
AgoBandFormat format = new
AgoBandFormat(cursor.getProperty(AgiRowCursor.BANDNAME));
This works because the band name for a given row is available as the built-in property AgiRowCursor.BANDNAME.
You can modify any runtime attribute of the view using the View API. (This applies to both static and dynamic views.) For example, you might change the color of a column or band based on the particular dataset it is using; you might decide to change the font of one of the columns to add emphasis to its data.
To change an attribute, follow these steps:
(To force a repaint, call the AgcView.setAgoViewFormat() method.)
The following section provides examples of how to change some common column or band attributes.
To obtain the object to change might require several steps depending whether the object that you want to change is a column, a band, or a view format. For example, if you want to change the column width, you have to get the column. To get the column you have to:
To begin, you must obtain an AgoViewFormat, using the AgcView.getAgoViewFormat() method. Once you have the AgoViewFormat, you can use it to access the bands, and so on, until you get the object that you want.
You can obtain a specific band using the getBandFormat() method. It has two variants: one requires the band index, the other requires a band name. Both variants return an AgoBandFormatBase. AgoBandFormatBase is an abstract base class for band formats. You must cast it to the appropriate AgoBandFormat object in order to use it.
The following example illustrates how to obtain the view format for the departments view, how to obtain the band format for the first band, and how to cast the AgoBandFormatBase appropriately.
AgoViewFormat vfmt = departments.getAgoViewFormat();
//Get the band format for the view
AgoBandFormatBase bbfmt = vfmt.getBandFormat(0);
AgoBandFormat bfmt = (AgoBandFormat) bbfmt;
Getting header bands
To get the header band, you must use the AgoViewFormat.getHeaderBandFormat() method instead of the getBandFormat() method.
Once you have a band format, you can obtain information about its columns using the getColumnFormat() method.
The getColumnFormat() method returns an AgoColumnBase object, which you must cast to the appropriate object before you can use it. This example shows how to get the column format for the first column in the view and how to cast it to an AgoColumnText object (assuming that you know that it is not an AgoColumnSpacer or an AgoColumnImage).
//Get the Column Format for the first column in the view
AgoColumnBase cfmt = bfmt.getColumnFormat(0);
//Cast AgoColumnBase to AgoColumnText
AgoColumnText ctext = (AgoColumnText) cfmt;
Now that you have the view format, the band format, and the column format, you can start to manipulate the attributes of the view at each level.
You can change attributes that specify size, color, width, and so on.
Changing column width
To change the width of a specific column, call the setWidth() method. Make sure that you test the view carefully when you specify a fixed width. If the data is too large for the specified width, the values in the column are cropped.
Changing column text color
For text editor, hierarchy, and text column types, you can change the text color of a specific column by calling the setColor() method.
Changing column text font
You can also set the column's text font by creating an AgoFontIdentifier object and assigning it to the column. To create an AgoFontIdentifier object, call the AgoFontIdentifier constructor. Assign it to the column using the setFontIdentifier() method.
Making changes visible
After you have made all of the changes that you think are necessary for the view, you must call the setAgoViewFormat() method to repaint it. Otherwise, the changes that you make will not be immediately visible in the runtime version of the view.
This example shows how you to call the setAgoViewFormat() method for a view called departments and a view format called vfmt.
departments.setAgoViewFormat(vfmt);
Column example
This example shows how to set the column width, text color, and font for a column called ctext.
//Set the column width for the first column
ctext.setWidth(30);
//Create a new font identifier for the first column
AgoFontIdentifier newFont=new AgoFontIdentifier("TimesRoman",
AgoFontIdentifier.ITALIC, 20);
//Set the font identifier for the first column
ctext.setFontIdentifier(newFont);
//Change the text color of the first column
ctext.setColor(Color.red);
.
.
.
view.setAgoViewFormat(vfmt);
Modifying attributes based on data content
You can change the appearance of a data band based on its data value using a special technique described in the "Dynamically Formatting Data in Views" technique.