Show / Hide Table of Contents

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 : IPlugin
Remarks

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:

EventCall / action taken
ConstructionGetButtonItems() is called once, returning an array of items. Buttons are shown from left to right in the order they are returned
Row selection changesThe 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 popupBefore 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 clickedIn Windows, the Execute delegate is called, and its result value processed as described in its comments. In Web, the is executed in the Browser.
Mouse doubleclick on rowIf 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:

SignatureMeaning
No arguments/no constructorYour 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 hWndYour 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:

Provider returnsAction taken in archive
PrimaryKey+RowType matchThe existing row is updated with the values from the provider
PrimaryKey+RowType mismatchA new row is added
Existing row not matched by new provider resultPreviously selected row is deleted from 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:

Provider returnsAction taken in archive
PrimaryKey+RowType matchThe existing row is updated with the values from the provider
PrimaryKey+RowType mismatchA new row is added
Existing row not matched by new provider resultPreviously selected row is deleted from 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:

Provider returnsAction taken in archive
PrimaryKey+RowType matchThe existing row is updated with the values from the provider
PrimaryKey+RowType mismatchA new row is added
Existing row not matched by new provider resultPreviously selected row is deleted from 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

Extension Methods

EnumUtil.MapEnums<From, To>(From)
Converters.MapEnums<From, To>(From)
© SuperOffice. All rights reserved.
SuperOffice |  Community |  Release Notes |  Privacy |  Site feedback |  Search Docs |  About Docs |  Contribute |  Back to top