IlsSwRepresentation

Each time a new view is requested, the server asks the component to create a new instance of the class IlsSwRepresentation. This class derives from IlsRepresentation, which is itself a subclass of IlsRpObject. Therefore, IlsSwRepresentation inherits all the features of IlsRpObject.

The class IlsRepresentation is the very first class to be instantiated by the component. The classes IlsSwTable and IlsSwRow cannot exist if they do not belong to a representation because their constructors take a reference to this representation as their first argument. Within the Server/Views mapping, the representation is actually an instance of IlsSwRepresentation. It has two main attributes:

resource (string): This attribute is actually the name of the .ilv file that contains the description of the representation. This file is located by the mvsw library through the variable ILVPATH. See Structure of a Server/Views .ilv File for a description of .ilv files.

resource (IlsMvFile): The resource attribute can be specified as an instance of the class IlsMvFile. In that case, the server sents the contents of the .ilv file instead of its name and the component does not need to have read access to the file. See Using the IlsMvFile Type for more information.

sds (IlsSwServerDataSource): This attribute, if supplied, requests the representation to re-use this Server data source instead of reading it from the .ilv resource file. Therefore, whenever this attribute is supplied, the resource attribute is ignored and the Server data source is used directly. If the panel attribute (described hereafter) is not supplied, the panel that holds the Server data source, if any, is used as the current panel.

panel (IlvGadgetContainer): This attribute, if supplied, requests the representation to re-use this gadget container. This attribute can be set when the panel that contains the view is not the same as the panel that contains the Server data source. Such is the case if the Server data source is a global data source (see the Rogue Wave Views documentation for details).

All the representation attributes we have just described are set during the first notification cycle that is carried out after the view has been opened.

They are used during the first call to the member function IlsSwRepresentation::endS2CUpdate to instantiate a panel (if applicable) and to retrieve a Server data source.

Notes:

1. About the attributes “panel” and “sds”: Rogue Wave Server Studio maps either of these attributes (if supplied) to the first and second view parameters so that they can be passed as arguments to the openView member functions.

2. These attributes can be set via the API. Because of certain limitations in the communications layer, their address is not passed to the protocol. Instead, a special index is passed that allows the library to retrieve these addresses transparently. This is why these indexes appear in the protocol trace, not the addresses that were registered.

Within the Server/Views mapping, a dynamic view needs its Server data source to open properly. This Server data source is held by an Rogue Wave Views gadget container.

The Server data source already exists in the component application and you have supplied it as a parameter when opening the view.

By using the panel view parameter: the representation looks for the gadget container and uses the first instance of a Server data source found in this container as its Server data source. Only Server data sources whose view name matches the view that is being opened are taken into account.

When the Server data source is already used by an opened view, Rogue Wave Server tries to close the corresponding representation by calling the virtual member function IlsSwRepresentation::onNewRpInSDS. By default, this method closes the representation so that the new representation can re-use the Server data source.

In that case, the representation creates a gadget container, reads the resource file specified in the view specification, and creates an instance of a Server data source. The representation is then said to “own” the panel. As a consequence of this “ownership’, the panel will be destroy (if it has not been already been destroyed) when the representation itself is destroyed.

If a gadget container factory has been supplied, the representation uses it to create the gadget container. (See the class IlsSwGadgetContainerFactory in the Rogue Wave Server Reference Manual for more information on the factory).

Once the container is created, the representation tries to read the resource file. However, if the resource file has already been read or a graphic object has been added to the container by means of a gadget container factory, the representation does not try to read the resource file.

If the resource file is not found on the path set by the environment variable ILVPATH, the representation displays a file browser and prompts the user to locate the file. The panel is then displayed.

The representation installs a destroyCallback so that the representation will be closed when you close the panel. If you have read or instantiated an object in this container by yourself, you are responsible for installing your own destroyCallback.

The name of the panel is the view name. But if an instance of IlvApplication has been associated with the component, and if a panel with this name already exists in this application, the panel name becomes viewName_n, where n is the first number that does not match an existing panel in the application.

Predefined properties are the following representation attributes of the class IlsSwRepresentation. They are associated with modifiers by means of ILS_RP_ATTR macros.

title (string): This attribute can be used to change the panel title dynamically. The panel is identified as follows:

iconTitle (string): This attribute can be used to change the icon title of the panel dynamically. The panel is identified as follows:

viewType (string) : This attribute is not used by Rogue Wave Server but can be useful if you derive the class IlsSwRepresentation or if you install a gadget container factory to differentiate between several types of view. You can retrieve its value by calling the function IlsSwRepresentation::getViewType.

The class IlsSwRepresentation features many callbacks that are called when an event occurs on the representation. Here are the main ones. (See the Reference Manual for details).

Warning: Do not delete the current representation while a callback is called.

This callback is called during execution of the function IlsRpObject::afterInit,—that is, after the constructor of IlsSwRepresentation.

This callback is called from the destructor of IlsSwRepresentation. It is no longer possible to call any virtual method on this object.

This callback is called when the representation panel and Server data source
are fully initialized, at the end of the first call to the member function IlsSwRepresentation::endS2CUpdate.

If you want to make additional modifications to the objects that were read in the .ilv file, you can use the function IlsSwRepresentation::AddCallback by passing it the callback IlvReadCallbackSymbol along with your callback. The callback you supply to this function will be called once the .ilv file has been read. It receives as its parameters the IlvGadgetContainer object that was used to read the graphic objects and the current instance of IlsSwRepresentation.