Programmer's Guide

Chapter 17   Using Java-based Views

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:

About Java-based view controls   Top of page

SilverStream provides these two Java-based view controls:




A class that you construct programmatically using the Form Designer's Programming Editor.

This is referred to as a dynamic view.


The class constructed by the SilverStream View Designer. AgcViewDownloadable is a subclass of AgcView.

This is referred to as a static view

View components   Top of page

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).

The components include:



View container

Represented by the AgoViewFormat object.

Describes the overall physical attributes of the view such as: background and caret color, background image, tool tip, help page, and whether the view allows multi-row selection.

An AgoViewFormat is composed of bands.


Represented by the AgoBandFormat object.

Describes the physical characteristics that are common across data or header rows such as: background color, indentation, transparency, and border appearance.

You typically define two band formats: one that describes the header row and one that describes the data rows. But you can define multiple band formats each describing a different kind of data row.

You can refer to the band programmatically by its name.

An AgoBandFormat is composed of columns.


Represented by an AgoColumnXXX format object.

SilverStream supports multiple AgoColumnXXX format types which can be used to display different kinds of data (for example, text or images).

More about columns

SilverStream provides the column formats described in the following table:

Column class



The base column format class.

You typically do not instantiate this object, but might use it when you want to obtain a column but do not know its type. For example, you might call:

  AgoColumnBase colfmt= 

You can then cast the AgoColumnBase to the appropriate column type.


Allows you to display a check box in the column.

A read-write column type.


Allows you to display a radio button in the column.

A read-write column type.


Allows you to display a combobox control in the column.

A read-write column type.


Allows you to display a SilverStream form control in the column.

The form has many of the same attributes as any SilverStream form control, but the form cannot be data-bound. However, the form used in the column may manipulate the data from the row in which it appears.

A read-only column type.


Allows you to define the format properties of a hierarchical column.

A read-only column type.


Allows you to display an image instead of text.

A read-only column type.


Allows you to display an integer spinner field in the column.

A read-write column type.


Allows you to create fixed-width space between columns.

A read-only column type.


The most common column style. You can use it to display any kind of text-based data.

A read-only column type.


Allows users to edit the text-based contents of the column.

A read-write column type.

Choosing a view control   Top of page

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

Application requirement

Use dynamic view?

Use static view?

The source of the data is a relational table



The source of data is a DSO, an AgcData control, or a user-written class (that implements AgiRowCursor)



Do you know the format of the data at design time?



Do you know the format of the data at runtime only?

(For example, is it necessary for the user to access any number of different Data Source Objects?)



Is the column layout static and known at design time?

You can, but probably better to use static view.


Is the column layout likely to change depending on runtime circumstances (for example, certain users should not see certain columns)



You want to implement your own data caching



Do you need to show hierarchical data


While it is possible, it is very difficult.


Occurs automatically when you specify fields.

How are you deploying this view?

Java forms only.

Pages directly or Java forms.

Creating dynamic views   Top of page

To create a dynamic view, you programmatically create each column, band and view format object in the following order:

  1. Create an AgoViewFormat.

  2. Create one or more AgoBandFormats.

  3. Create and initialize one or more AgoColumnFormats.

  4. Append the AgoColumnFormats to the AgoBandFormats.

  5. Append the AgoBandFormats to the AgoViewFormat.

  6. Instantiate an AgcView.

  7. Initialize AgcView with an AgoViewFormat and a data object (that implements AgiRowCursor).

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.

Creating AgoViewFormats   Top of page

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(); 

Creating AgoBandFormats   Top of page

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.

Creating columns   Top of page

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.

Setting initial values for columns

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,, 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,, 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.

Appending columns to bands   Top of page

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.


The order in which you append the columns determines the column order (left-to-right) on the band.

Appending bands to view formats   Top of page

To add bands to a view format, you call the AgoViewFormat.appendBandFormat() method. This example shows how to add a band format called bfmt.


Creating a header band

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.


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.

Instantiating an AgcView   Top of page

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.

Using the Form Designer

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:

  1. Open the Form Designer.

  2. Choose the dynamic view control located on the Other tab of the control panel.

  3. Drag the control from the control panel onto the form.

  4. Use the Property Inspector to specify its properties. Typically, you would set Name, Size, and Location.


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();  

Views and data   Top of page

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.

Static views and data   Top of page

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:


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:


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.

Dynamic views and data   Top of page

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:

  1. Place an AgcData control on the form.

  2. Use the Property Inspector to specify the AgcData's properties (Column Names and Column Expressions).

  3. In the event where you instantiate the Agcview, call the 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.

Navigating and manipulating data   Top of page

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 =  

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.

Getting data from an AgoTreeDataManager   Top of page

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:

Manipulating view formats at runtime   Top of page

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:

  1. Obtain the object that you want to change (for example, the column)

  2. Modify the attributes (for example, the width)

  3. Repaint the view to display the change

    (To force a repaint, call the AgcView.setAgoViewFormat() method.)

The following section provides examples of how to change some common column or band attributes.

Obtaining the object to change   Top of page

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:

  1. Get the AgoViewFormat

  2. Get the AgoBandFormat

  3. Get the AgoColumnFormat

Getting view formats

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.

Getting band formats

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.

Getting column formats

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.

Modifying runtime attributes   Top of page

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.


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 
//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
//Change the text color of the first column

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.

Copyright © 2000, SilverStream Software, Inc. All rights reserved.