21.7 Creating Custom Forms

Tradepoint allows you to add your own windows, and override the default windows for dialogs and other functionality. In fact you could completely reproduce the functionality of the Customer window with our plug-in architecture if you wished.

Tradepoint uses "Visual Inheritance" to make developing screens quick and easy. To implement an inherited screen, please create a new form, then go to the code behind and change the inheritance as necessary. When switching back to design view the screen will automatically update. (It is highly recommended that you do not change a window to a different type once you have specified the type once and viewed in the designer as you will get compile errors!)  There are a number of different forms that you can use to base your new screen on:

Tradepoint.Windows.frm.BaseForm - This is the most basic form within Tradepoint. This provides you with basic error handling, and a connection to the database and little else.  You can build your own logic for almost all other functionality from this window if you choose or use one of the more feature-rich screens.

Tradepoint.Windows.frm.Default.Form - This screen will provide you with the same layout and setup as the Customer screen within Tradepoint with the left search area and the area on the right for creating the editing interface. There are a number of events that you can implement that will allow you to handle Validation, Updating etc. that are shared with the other 2 main window types (see below).  In addition there are several screen specific events:

AddRecord: This allows you to Over ride the default creation of a new record bound to the data source.

RecordAdded: Fired immediately after the new record is created

RecordChanged: Fired immediately after a record is selected in the results.

DeleteRecord: Allows you to override the deletion process if required for any reason

LoadActions: Allows you to implement your own Tools tab beside the advanced search for working with the results from a quick or Advanced Search.

LoadAdvancedSearch:   Allows you to implement your own Advanced Search window that implements Tradepoint.Windows.Searches.AdvancedSearchBase. This function is called once to load the new search area the first time. It is done this way to conserve resources. It is strongly recommended that you do not load your search as part of the initial load of the screen.

QuickSearch: Allows you to implement a quick search routine. Generally this will be used in concert with the protected method "FillResults" to fill the results list passing your current SQL query that will display the information. Note that the Event Args include the value that was quick searched on.

Search: Allows you to implement the search routine. See notes on the QuickSearch event for how to properly handle this.

Properties and Methods

DeleteSecurityKey: Allows you to configure the security key that will be read for the currently logged in user to determine if the user can delete a record.

ChangeSecurityKey: The security setting that will be read to determine if the user is allowed to change the data on the form. The form will be locked if the result is false.

AddSecurityKey: Allows you to configure the security key that will be read for the currently logged in user to determine if the user can add a record.

PrintSecurityKey: Allows you to configure the security key that will be read for the currently logged in user to determine if the user can print reports based on their search results.

DisplayField: This is the database field name that will be used as the Display Name for the currently selected record (i.e. "Name")

Note: The bottom right main area to the window must have panels added to it with your controls. You can add panels (or "Pages") using the collection on the wPage control.  For more information about how to hook up the buttons in the ribbon to your page, please see below.

Tradepoint.Windows.frmDefaultDialog

This window allows you to implement windows similar to the Quote or Invoice screens within Tradepoint with the same functionality.  This window is specifically designed to work on one record at a time and can be viewed as a single record version of the frmDefaultForm window. In addition to the shared events listed below, this window also implements:

PrintReport: This event allows you to add custom reports and present the user with a dialog of available reports to print for the specific item.

Properties and Methods

InitialState: This allows you to report to the base constructor, the state of the window such as new and edit.

NoSaveAbility: This allows you to lock the form to prevent saves.

HistoryVisible: Allows you to control if the form will show the History button and automatically lookup history based on the current ID.

ShowPrint: This controls if the screen allows printing.

LockDialog: Locks the dialog and prevents data entry and saving.

UnlockDialog: Unlocks the dialog and allows data entry and saving.

ChangeSecurityKey: The security setting that will be read to determine if the user is allowed to change the data on the form. The form will be locked if the result is false.

Tradepoint.Windows.frmSimpleDialog

This window is designed to work much like an advanced MessageBox and does not allow multiple pages, nor does it have a static top area. In addition, this window is designed to work as a full Dialog outside of the MDI structure and thus the ribbon is hidden on this screen. It shares the ValidatingRecord and UpdatingRecord events below.

Shared Events

The following Events apply to the two default windows and the Simple Dialog with the exception of the PageChanged event.  These are used for data validation, loading and saving.

PageChanged: This event allows you to dynamically load your data and should be used in preference to the RecordChanged or the constructor on your window as much as possible (i.e. only load that which will be immediately visible in your constructor or RecordChanged events).  The Event Args provides you with the information about the reasons for the change and the panel that is being changed to. To get the ID of the current record use the protected ID property.

ValidatingRecord: This event allows you to validate the current page for any data entry errors before save and cancel if any errors are reported. Typically errors will be reported using the ErrorText property on the Tradepoint.Windows.Controls so that the user is notified in a consistent way.  e.Cancel allows you to cancel the update and allow the user to correct their entry mistakes.

UpdatingRecord: This event allows you to persist your data to the data source. It is up to you to persist this information however you see fit. The screen provides many options for data loading/saving. Please see below for more details.

Shared Properties

Each screen provides the following properties that will help you to manage the state of the window:

ID: This is the property that stored the GUID identifying the unique record being edited. This should be set in your constructor in the case of a Dialog if creating a new record. Otherwise the process of setting this item is automatically handled for you for the other windows.

DefaultPage: This is a reference to the default button on the ribbon and thus the default page that will be selected on first run and add new functions in the window.

Shared Methods

SetSecurity(FirstRun): This method allows you to control the security for the current record. The first run property determines if this is a new record or the first time the window has been loaded.

Print: Allows you to override the print functionality on the window and print your own reports.

RevertChanges: This method will allow you to revert changes and is called when the user hits the escape key on the keyboard. The default settings are normally sufficient and should always be called within your implementation.

ClearControls: This method will allow you to clear the values of all of the controls on the form and send the window back to its defaults.

Change: Allows you to notify the window that you want the window to think that it has been changed. In the case of a dialog control the save and cancel buttons will be displayed as a result of this method call if not already visible.

ReturnSecurityPermission(ItemName): Allows you to retrieve a security permission by name for the current record and user.

ClearErrors: Allows you to clear all errors on controls.

UpdateRecord: Instructs the dataBinding (see below) to update the record with all of the Pre-requisite information handling concurrency violations etc.