Interface IArchiveControlEventHandler
This interface defines a handler for archive row events - what should happen when a user double-clicks or otherwise operates on a row of a custom archive; and which action items (buttons, menus) should be shown
Namespace: SuperOffice.CRM.ArchiveLists
Assembly: SoDataBase.dll
Syntax
public interface IArchiveControlEventHandler : IPluginRemarks
Custom archives will attempt to instantiate an object implementing this interface, and marked with an attribute giving the same name as the archives' data provider. If such an instance is created, it will then be called as follows:
| Event | Call / action taken |
|---|---|
| Construction | GetButtonItems() is called once, returning an array of items. Buttons are shown from left to right in the order they are returned |
| Row selection changes | The CanExecute method is called on each action originally returned from GetButtonItems(), whenever the set of currently selected rows changes (including on reload, where no rows are initially selected). Return values are used to enable/disable/show/hide buttons. |
| Right-click/context menu popup | Before the menu is shown, then GetMenuItems(RowInfo[]) method is called to get the content of the menu. Then, the CanExecute delegate on each returned menu item is called, to determine whether it should be visible and enabled. The menu is then shown. |
| Menu or button clicked | In Windows, the Execute delegate
is called, and its result value processed as described in its comments. In Web, the |
| Mouse doubleclick on row | If an 'open' action has been declared, then it is processed; otherwise nothing happens |
Row selection, double-clicking/Enter key, Add button, Delete button/Del key are special events that have a strongly typed interface; other actions are defined and handled by the generic GetMenuItems(RowInfo[]) and GetButtonItems() methods, and the delegates embedded in their return values.
There are two possible constructor signatures for this class:
| Signature | Meaning |
|---|---|
| No arguments/no constructor | Your code does not care about the "guiName" and "hWnd" parameters. This is the case if there is only the one archive with this provider name, or if the behaviour of all archives for this provider should be identical. It also means that you do not plan to invoke GUI methods that require the knowledge of the Win32 HWND of the archive control itself. |
| string guiName, int hWnd | Your code needs at least one of these two items, either to differentiate behaviour based on the gui control name (between different archives for the same provider); or you want to perform GUI operations that require the Win32 HWND of the archive control window. |
The factory code will automatically recognize and call either of these two constructors. You can also omit defining a constructor altogether if you have no initialization code. Constructors with other signatures will not cause failures, but they will not be called.
Methods
AddRow(ArchiveRestrictionInfo[])
Handler called when the user clicks the Add button or menu item
Declaration
ArchiveRestrictionInfo AddRow(ArchiveRestrictionInfo[] context)Parameters
| Type | Name | Description |
|---|---|---|
| ArchiveRestrictionInfo[] | context | Current archive restrictions that define the context of the archive |
Returns
| Type | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| ArchiveRestrictionInfo | The result is processed as follows: If a null value is returned here, no action is taken by the archive control If a non-null archive restriction is returned, then it is added to the other restriction currently in force, and the data provider is called. The result set is then processed depending on matching primary keys and row types of the result set with those already in the selected rows only of the archive:
This delegate should thus return an archive restriction that refetches the currently selected rows, as far as is relevant; and this result set will update/replace/extend the currently selected rows. If there are no currently selected rows, then no rows can/will be deleted from the archive |
CanAddRow(ArchiveRestrictionInfo[])
Can a row be added? If the return value does not have the Write right set, then the Add button will be disable and the return values' Reason will be set as the tooltip
Declaration
FieldRight CanAddRow(ArchiveRestrictionInfo[] context)Parameters
| Type | Name | Description |
|---|---|---|
| ArchiveRestrictionInfo[] | context | Current archive restrictions that define the context of the archive |
Returns
| Type | Description |
|---|---|
| FieldRight | Desired state of Add button; the CanUIUpdate is bound to the enabled state. If false, then the Reason is shown as the tooltip to explain to the user why the button is disabled |
DeleteRows(RowInfo[])
Delete one or more rows
Declaration
ArchiveRestrictionInfo DeleteRows(RowInfo[] rowInfo)Parameters
| Type | Name | Description |
|---|---|---|
| RowInfo[] | rowInfo | Information identifying the rows to be deleted |
Returns
| Type | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| ArchiveRestrictionInfo | The result is processed as follows: If a null value is returned here, no action is taken by the archive control If a non-null archive restriction is returned, then it is added to the other restriction currently in force, and the data provider is called. The result set is then processed depending on matching primary keys and row types of the result set with those already in the selected rows only of the archive:
This delegate should thus return an archive restriction that refetches the currently selected rows, as far as is relevant; and this result set will update/replace/extend the currently selected rows. If there are no currently selected rows, then no rows can/will be deleted from the archive |
EditRow(RowInfo)
Edit one row (show detail dialog, jump to other application, etc)
Declaration
ArchiveRestrictionInfo EditRow(RowInfo rowInfo)Parameters
| Type | Name | Description |
|---|---|---|
| RowInfo | rowInfo | Information identifying the row to be deleted |
Returns
| Type | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| ArchiveRestrictionInfo | The result is processed as follows: If a null value is returned here, no action is taken by the archive control If a non-null archive restriction is returned, then it is added to the other restriction currently in force, and the data provider is called. The result set is then processed depending on matching primary keys and row types of the result set with those already in the selected rows only of the archive:
This delegate should thus return an archive restriction that refetches the currently selected rows, as far as is relevant; and this result set will update/replace/extend the currently selected rows. If there are no currently selected rows, then no rows can/will be deleted from the archive |
GetButtonItems()
Get button actions for a custom archive; called once during construction; see class remarks
Declaration
RowActionItemInfo[] GetButtonItems()Returns
| Type | Description |
|---|---|
| RowActionItemInfo[] | Array of button items to be included in toolbar; their visibility and enabled state can be determined at a later point depending on the selected rows, through the CanExecute method |
GetImage(String)
Return a graphic image corresponding to an image hint; or null if the hint refers to a standard graphic that is already present in the calling client code's graphic library
Declaration
Image GetImage(string iconHint)Parameters
| Type | Name | Description |
|---|---|---|
| String | iconHint | Image to fetch |
Returns
| Type | Description |
|---|---|
| Image | Image, or null; if null then the system will attempt to find a corresponding standard icon |
GetMenuItems(RowInfo[])
Get context menu items for a particular set of rows; called when user right-clicks to trigger popup menu; see class remarks
Declaration
RowActionItemInfo[] GetMenuItems(RowInfo[] rowInfo)Parameters
| Type | Name | Description |
|---|---|---|
| RowInfo[] | rowInfo | Array with information about selected rows; empty array if no rows are currently selected |
Returns
| Type | Description |
|---|---|
| RowActionItemInfo[] | Array of menu items to be included in menu |
HasAddButton()
Should the system-supplied Add button/context menu item be shown on this archive?
Declaration
bool HasAddButton()Returns
| Type | Description |
|---|---|
| Boolean |
HasDeleteButton()
Should the system-supplied Delete button/menu item be shown on this archive? The enabled/disabled state will be set automatically based on the selected rows' RowRight sentry information
Declaration
bool HasDeleteButton()Returns
| Type | Description |
|---|---|
| Boolean |