IlsSwComponent

Category

Dynamic view-related class (Server/Views integration)

Inheritance Path

IlsMvComponent
➥ IlsSwComponent

Description

This class allows you to create an Rogue Wave Views application component. This component has a predefined behavior.

Library

<mvsw>

Header File

#include <ilmvsw/mvswcomp.h>

Synopsis

class IlsSwComponent : public IlsMvComponent

{

public:

Initialization

static void Initialize(IlvDisplay*,

int argc = 0,

char** argv = 0);

static void Initialize(IlvApplication*,

int argc = 0,

char** argv = 0);

static void SetApplication(IlvApplication*);

static IlvApplication* GetApplication();

Execution

static void Run(IlvApplication* = 0);

Connection Panel

static void SetNoConnectionPanel(IlsBoolean);

static void HideConnectionPanelAtInit(IlsBoolean);

Finding Data Sources

virtual IlsSwServerDataSource** findDataSourcesInIlv

(IlvGadgetContainer*,

const IlsString& fileName,

unsigned int& count,

IlsBoolean promptPath = IlsTrue);

static IlsSwServerDataSource** FindDataSourcesInContainer

(IlvGadgetContainer*,

unsigned int& count);

Error Handling

virtual void recvMessage(const IlsMvMessage::SvMsg&);

static void HandleMessage(const IlsMvMessage::SvMsg&);

static void HandleMessage(const IlsString&);

static void HandleWarning(const IlsString&);

static void HandleError(const IlsString&);

View Parameters

static void DeclareViewParameterDataSource

(IlsSwServerDataSource*);

static void DeclareViewParameterContainer

(IlvGadgetContainer*,

const IlsString& viewName = IlsString::Null);

static void PrepareViewParameters(const IlsString& viewName,

IlsSwServerDataSource* sds,

IlsMvValue*& argv,

IlsCbArgNb& argc,

IlsMvValue*& ackArgv,

IlsCbArgNb& ackArgc,

IlsCbArgNb& resIndex,

IlsSwOpenViewCallbackType cb = 0,

IlsAny arg = 0);

Opening a New View

virtual void openSwView(const IlsString& objId,

const IlsString& viewId,

IlsSwServerDataSource* sds,

IlsMvValue* params = 0,

int paramsNb = 0,

IlsBoolean force = IlsFalse);

IlsSwOpenViewCallbackType cb = 0,

IlsAny arg = 0);

virtual void openSwView(const IlsString& objId,

const IlsString& viewId,

IlvGadgetContainer* cont,

IlsSwServerDataSource* sds,

IlsMvValue* argv,

IlsCbArgNb argc,

IlsMvValue* ackArgv,

IlsCbArgNb ackArgc,

IlsCbArgNb resultIndex,

IlsBoolean force = IlsFalse,

IlsSwOpenViewCallbackType cb = 0,

IlsAny arg = 0);

virtual void openingViewFromConnectionPanel

(const IlsString& objId,

const IlsString& viewId,

IlsBoolean force);

virtual void ackOpenView(const IlsMvValue* ackArgv,

IlsCbArgNb ackArgc);

static IlvGadgetContainer* GetContainerPtr(int);

static IlsSwServerDataSource* GetDataSourcePtr(int);

Blocking Mode

IlsBoolean getBlockingMode() const;

void setBlockingMode(IlsBoolean);

static IlsBoolean GetDefaultBlockingMode();

static void SetDefaultBlockingMode(IlsBoolean);

Component Control

static IlsSwComponent* GetComponent(IlsMvComponentId);

static void SetUseDragDropInteractor(IlvBoolean);

static void SetUseDragDropInteractorFlags

(IlsSwDragDropInteractorFlag);

Converting an Rogue Wave Views/Data Access Type to an Rogue Wave Server Type

static void DeclInFormConverter(const IliDatatype*,

IlsSwInFormConverter);

static void UndeclInFormConverter(const IliDatatype*);

static IlsSwInFormConverter GetInFormConverter

(const IliDatatype*);

static IlsBoolean ConvertInFormType(const IliValue&,

IlsMvValue&);

Converting an Rogue Wave Server Type to an Rogue Wave Views/Data Access Type

static void DeclServerConverter(const IlsString& userTypeName,

IlsSwServerConverter converter);

static void UndeclServerConverter

(const IlsString& userTypeName);

static IlsSwServerConverter GetServerConverter

(const IlsString& userTypeName);

static IlsBoolean ConvertServerType(const IlsMvValue&,

IliValue&);

Callbacks

static void AddCallback(IlvSymbol* symbol,

IlsSwComponentCallbackType,

IlsAny = 0,

IlsSwComponent* = 0);

static void RemoveCallback(IlvSymbol* s,

IlsSwComponentCallbackType,

IlsAny = 0,

IlsSwComponent* = 0);

Callback Symbols

static IlvSymbol* ComponentCreatedSymbol();

static IlvSymbol* ComponentDestroyedSymbol();

static IlvSymbol* BeginC2STransactionSymbol();

static IlvSymbol* CommitC2STransactionSymbol();

static IlvSymbol* RollbackC2STransactionSymbol();

Other Functions

virtual IlsString getIlvFileName(const IlsString&);

static IlsBoolean HasExited();

};

Member Functions

Initialization

[static] void Initialize(IlvDisplay*, int argc =0, char** argv = 0);

This static member function takes a valid Rogue Wave Views IlvDisplay object as its first argument. It must be called to initialize the Rogue Wave Server/Rogue Wave Views component before opening any dynamic views that are using classes from the Rogue Wave Server/Rogue Wave Views library.

[static] void Initialize(IlvApplication*, int argc =0, char** argv = 0);

This static member function takes a valid IlvApplication object as its first argument. The other two arguments argc and argv are used to interpret some specific command-line options.

This application is used to store all the panels that have been created implicitly. A panel is said to be implicitly-created when an Rogue Wave Server/Rogue Wave Views view is opened without any container or Server-data-source view parameters being specified.

[static] void SetApplication(IlvApplication*);

This static member function associates an application with the component.

[static] IlvApplication* GetApplication();

This static member function returns the Rogue Wave Views application that has been associated with the component if that component was initialized using the member function Initialize(IlvApplication*,...).

Execution

[static] void Run(IlvApplication* = 0);

This static member function starts the main loop of the application component. If an instance of IlvApplication is passed, this function calls the run method of the application, otherwise it calls the global function IlvMainLoop.

Connection Panel

[static] void SetNoConnectionPanel(IlsBoolean);

This static member function can be called before the application component has been initialized to control whether the connection panel is to be created.

[static] void HideConnectionPanelAtInit(IlsBoolean);

This static member function can be used to control whether the current connection panel, if any, is visible when the component starts.

Finding Data Sources

[virtual] IlsSwServerDataSource** findDataSourcesInIlv

(IlvGadgetContainer*,

const IlsString& fileName,

unsigned int& count,

IlsBoolean promptPath = IlsTrue);

This virtual member function loads the .ilv file passed as the fileName parameter into the gadget container passed as the first parameter. If the parameter promptPath is set to IlsTrue, the function opens a file browser that lets you locate the file if it is not on its path. Any new directories used to find a file are added to the local path of the component.

This function returns an array of all the Server data sources loaded into the gadget container. The array must be freed using delete [] when done.

[static] IlsSwServerDataSource** FindDataSourcesInContainer

(IlvGadgetContainer*,

unsigned int& count);

This static member function can be used to retrieve an array of Server data sources that can then be declared as view parameters. This array must be freed using delete [] when done.

Error Handling

[virtual] void recvMessage(const IlsMvMessage::SvMsg&);

This virtual member function displays a message sent by the server. By default, this function just calls the static member function HandleMessage.

[static] void HandleMessage(const IlsMvMessage::SvMsg&);

This static member function displays an error message. Depending on the severity
of the error, it just calls one of the functions HandleError, HandleWarning, or HandleMessage.

[static] void HandleMessage(const IlsString&);

This static member function adds the error message to the message log.

[static] void HandleWarning(const IlsString&);

This static member function displays the error message in a pop-up warning dialog box and adds it to the message log.

[static] void HandleError(const IlsString&);

This static member function displays the error message in a pop-up error dialog box and adds it to the message log.

View Parameters

[static] void DeclareViewParameterDataSource(IlsSwServerDataSource*);

This static member function declares a Server data source as a view parameter. Such a data source is also referred to as a preregistered data source.

When a view is opened through one of the functions IlsSwComponent::openSwView, IlsSwRow::onSwDereference or IlsSwTable::onSwDereference, the appropriate Server data source is supplied as a view parameter. You do not need to associate a preregistered data source with a representation name : the mvsw library automatically uses the right data source.

[static] void DeclareViewParameterContainer

(IlvGadgetContainer*,

const IlsString& viewName = IlsString::Null);

This static member function declares a gadget container as a view parameter. When a view is opened through one of the functions IlsSwComponent::openSwView, IlsSwRow::onSwDereference or IlsSwTable::onSwDereference, the appropriate gadget container is supplied as a view parameter.

If you provide the view name, the gadget container will be used only for that view.

If you do not provide a view name, the panel will be used for all views.

[static] void PrepareViewParameters(const IlsString& viewName,

IlsSwServerDataSource* sds,

IlsMvValue*& argv,

IlsCbArgNb& argc,

IlsMvValue*& ackArgv,

IlsCbArgNb& ackArgc,

IlsCbArgNb& resIndex,

IlsSwOpenViewCallbackType cb = 0,

IlsAny arg = 0);

This static member function can be used to initialize the predefined view parameters before calling one of the functions IlsMvComponent::openView, IlsRpObject::openView, or IlsRpObject::onDereference to open a view that uses Rogue Wave Server/Rogue Wave Views classes. The view will be opened using the provided Server Data Source, if any.

If the parameter sds is null, Rogue Wave Server tries to find a pre-registered Server Data Source for viewName.

If the parameter cb is not null, this method also installs a callback, which is called when the corresponding view is opened.

The function PrepareViewParameters should be called only once before the view-opening function is called, which means that you should use the returned parameter arrays when calling IlsMvcomponent::openView, IlsRpObject::openView, or IlsRpObject::onDereference.

This function assigns values to the parameters argc and ackArgc, as well as to the parameter resIndex, and allocates new arrays to the parameters argv and ackArgv.

You must call delete [] after having used these arrays if the corresponding number of elements is not null. However, if you have provided arrays for argv and ackArgv, they will not be deleted by the function PrepareViewParameters. The parameters you pass to these arrays are copied into the new arrays and they are positioned after the standard parameters installed by the function.

Opening a New View

[virtual] void openSwView(const IlsString& objId,

const IlsString& viewId,

IlsSwServerDataSource* sds,

IlsMvValue* params = 0,

int paramsNb = 0,

IlsBoolean force = IlsFalse);

IlsSwOpenViewCallbackType cb = 0,

IlsAny arg = 0);

This virtual member function calls the second openSwView function (described below) with a data source and without any container as its parameters.

[virtual] void openSwView(const IlsString& objId,

const IlsString& viewId,

IlvGadgetContainer* cont,

IlsSwServerDataSource* sds,

IlsMvValue* argv,

IlsCbArgNb argc,

IlsMvValue* ackArgv,

IlsCbArgNb ackArgc,

IlsCbArgNb resultIndex,

IlsBoolean force = IlsFalse,

IlsSwOpenViewCallbackType cb = 0,

IlsAny arg = 0);

This virtual member function opens the view viewId on the object objId. The view uses the supplied container and Server data source if the parameters cont and sds are supplied.

If the container is not provided, the Server data source holder is used instead.

If neither the Server data source nor the container are provided, Rogue Wave Server looks for a preregistered data source for this view (see the member function DeclareViewParameterDataSource).

If a Server data source is not found, a new panel is created when the view opens.

The argument IlsSwOpenViewCallbackType is a callback function that is called when the view is opened on the component side. This callback is called after all the representation objects that represent subscribed objects have been created. This means that the callback is not called until the creation notification has been fully processed on the component side.

Actually, it is called at the end of the first notification cycle for this view, that is, during the first call to IlsSwRepresentation::endS2CTransaction. It means that all representation objects related to this view are created when this callback is called.

This callback uses arg as an extra argument. Rogue Wave Server uses the ackArgv parameter from the virtual member function IlsMvComponent::openView to send an internal index, which is resent later by the server through one of the member functions IlsSwRepresentation::onCreation or IlsMvComponent::ackOpenView. This internal index is used to trigger the openView callback. Among the possible values:

ackArgv[0] is reserved for the result of openView, and

ackArgv[1] stores this internal index.


Note: The member functions IlsSwRepresentation::endS2CTransaction and IlsSwRepresentation::onCreation are therefore inherited from the class IlsRepresentation; therefore, you must call them if you derive that class and override the method.

[virtual] void openingViewFromConnectionPanel(const IlsString& objId,

const IlsString& viewId,

IlsBoolean force);

This virtual member function is called by the connection panel when the user opens a view. By default, this method opens the view by calling the member function openSwView.

[static] IlvGadgetContainer* GetContainerPtr(int);

When a view is opened by a call to the function openSwView, a container is passed as an index which is received by the instance of IlsSwRepresentation. In that case, the static member function GetContainerPtr helps you retrieve the address of the container from the index. This function returns 0 if the panel has already been destroyed.

[static] IlsSwServerDataSource* GetDataSourcePtr(int);

When a view is opened by a call to the function openSwView, the Server Data Source is passed as an index which is received by the instance of IlsSwRepresentation during its creation. In that case, the static member function GetDataSourcePtr helps you retrieve the address of the Server Data Source from the index. This function returns 0 if the Server Data Source has already been destroyed.

[virtual] void ackOpenView(const IlsMvValue* ackArgv,IlsCbArgNb ackArgc);

This virtual member function (which is inherited from the class IlsMvComponent) is called by Rogue Wave Server when a view has been opened on the server.

The first element of the ackArgv array contains a value of type char which stores an IlsOpenViewStatus status value. This status indicates whether the view has been opened. If the opening of the view has failed or if the view was already opened on the same origin, the ackOpenView function triggers the IlsSwOpenViewCallbackType callback. See the function IlsMvComponent::ackOpenView for more information.

Blocking Mode

IlsBoolean getBlockingMode() const;

This member function returns IlsTrue if the component is running in blocking mode.

void setBlockingMode(IlsBoolean);

This member function can be used to turn blocking mode on or off in the component. Blocking mode for the component means that the watch cursor is set when a component transaction is committed and no more component transactions is allowed until the first transaction is finished. Committing a second component transaction while the component is blocked results in an error message and the rollback of the second transaction.

[static] IlsBoolean GetDefaultBlockingMode();

This static member function returns the default value for the blocking mode.

[static] void SetDefaultBlockingMode(IlsBoolean);

This static member function can be used to set the default value for the blocking mode.

Component Control

[static] IlsSwComponent* GetComponent(IlsMvComponentId);

This static member function can be used to return an Rogue Wave Server/Rogue Wave Views component from the component identifier.

[static] void SetUseDragDropInteractor(IlvBoolean);

This static member function can be used to stop the drag-and-drop interactor from being used on the table gadget —an instance of IlsSwTableGadget— and on the hyper-reference gadget —an instance of IlsSwHRefGadget. By default, this interactor is active.

[static] void SetUseDragDropInteractorFlags(IlsSwDragDropInteractorFlag);

This static member function allows fine control over which aspects of the drag-and-drop interactor are enabled. By default, all interactions are enabled.

Converting an Rogue Wave Views/Data Access Type to an Rogue Wave Server Type

[static] void DeclInFormConverter(const IliDatatype*,IlsSwInFormConverter);

This static member function declares a new converter that lets you convert an instance of IliValue to an instance of IlsMvValue. If you use Rogue Wave Views types that are not supported by the Rogue Wave Server/Rogue Wave Views mapping, you must declare a converter.

The following Rogue Wave Views types are supported by default:

IliStringType

IliIntegerType

IliBooleanType

IliDoubleType

IliFloatType

IlsSwHRefType

[static] void UndeclInFormConverter(const IliDatatype*);

This static member function removes an Rogue Wave Views converter that was previously declared using the static member function DeclInFormConverter documented above.

[static] IlsSwInFormConverter GetInFormConverter(const IliDatatype*);

This static member function returns the current converter, if any, for an Rogue Wave Views type.

[static] IlsBoolean ConvertInFormType(const IliValue&, IlsMvValue&);

This static member function converts the instance of IliValue passed as its first parameter to the instance of IlsMvValue passed as its second parameter, if this conversion is possible. The function returns IlsFalse if the conversion is not possible.

Converting an Rogue Wave Server Type to an Rogue Wave Views/Data Access Type

[static] void DeclServerConverter(const IlsString& userTypeName,

IlsSwServerConverter converter);

This static member function declares a new converter that lets you convert an instance of IlsMvValue to an instance of IliValue. This function allows you to map Rogue Wave Server types to Rogue Wave Views types for use in dynamic view type specifications.

The first argument to this function is the name of the Rogue Wave Server user-defined type.

The second argument is the converter that will be used to convert a value of this Rogue Wave Servertype to a value of an Rogue Wave Views type.

Once the converter has been declared, Rogue Wave Server will call it each time an Rogue Wave Views cell needs to be assigned a value of the Rogue Wave Server user-defined type.

For the conversion to take place, you must also previously create an association between the Rogue Wave Server type and an Rogue Wave Views type using the static member function IlsSwUtility::AddNameAssociation.

[static] void UndeclServerConverter(const IlsString& userTypeName);

This static member function removes an Rogue Wave Server converter that was previously declared using the static member function DeclServerConverter documented above.

[static] IlsSwServerConverter GetServerConverter(const IlsString& userTypeName);

This static member function returns the current converter, if any, for the Rogue Wave Server user-defined type userTypeName.

[static] IlsBoolean ConvertServerType(const IlsMvValue&, IliValue&);

This static member function converts the instance of IlsMvValue passed as its first parameter to the instance of IliValue passed as its second argument if such a conversion is possible. This function returns IlsFalse if the conversion is not possible.

Callbacks

[static] void AddCallback(IlvSymbol* symbol,

IlsSwComponentCallbackType,

IlsAny = 0,

IlsSwComponent* = 0);

This static member function adds a callback to the component. The parameter symbol identifies which callback is to be added. If the component is null, the callback is called for all instances of IlsSwComponent.

[static] void RemoveCallback(IlvSymbol* symbol,

IlsSwComponentCallbackType,

IlsAny = 0,

IlsSwComponent* = 0);

This static member function removes a callback that was previously added using the static member function AddCallback described above.

Callback Symbols

[static] IlvSymbol* ComponentCreatedSymbol();

This static member function returns the symbol for the callback that can be called when a component is created. A component is considered created when it has been connected.

[static] IlvSymbol* ComponentDestroyedSymbol();

This static member function returns the symbol for the callback that can be called when a component is destroyed.

[static] IlvSymbol* BeginC2STransactionSymbol();

This static member function returns the symbol for the callback that can be called when a component transaction is started.

[static] IlvSymbol* CommitC2STransactionSymbol();

This static member function returns the symbol for the callback that can be called when a component transaction is committed.

[static] IlvSymbol* RollbackC2STransactionSymbol();

This static member function returns the symbol for the callback that can be called when a component transaction is rolled back.

Other Functions

[virtual] IlsString getIlvFileName(const IlsString&);

This virtual member function returns the full path for the file name passed as its parameter. This method opens a file browser and adds the new directory where the file was found to the local component path.

[static] IlsBoolean HasExited();

This static member function returns IlsTrue if the display has already been destroyed. It may means that the application is currently exiting.