CodeSnip Design Notes

GUI

The GUI is represented schematically below:

Main Menu / Main Toolbar

Main Display

Overview Pane

Displays an overview of the routines available in the code snip database. Contains 2 views:
(1) that lists all routines uncategorised
(2) that groups routines in categories.

Details Pane

Determines which if two detail panes is displayed: either a Detail pane or a Compiler pane. One of the two panes below is displayed:

Information Pane

Displays detail of currently selected item which can be one of

A routine: displays info about the routine.
A category: displays list of routines in category.
Header of uncategorised display: displays list of all routines with descriptions
Welcome page.

Compile Pane

Displays a page where a routine can be test compiled in one of installed versions of Delphi, or displays welcome page. If currently selected item is not a routine and not displaying welcome page this page carries a message saying to select a routine.

Status Bar

The GUI is divided conceptually into command and display subsystems. The command subsystem manages user input and the display subsytem handles output.

Each of the GUI components noted above takes some responsibility for processing commands and displaying data as described below.

Main Menu / Main Toolbar	Display: Most menu items and toolbar items have no specific objects used to manipulate the way they display. However, some, like the forward and backward navigation controls are managed by manager object. Commands: Each menu item and toolbar item has an associated action that is handled by event handlers in the main form (see below) or by custom actions.
Main Display	Display: The main display is managed by a master object that implements some of the high level display logic. It hands detailed display duties over to other display objects (below). Commands: This object has no command duties: it simply reports changes of display to the owner object (main form).
Overview Pane	Display: Manages the overview routine list (treeview) and the overview tabs (tab set). Clicking a tab causes a change of display format (either uncategorised or categorised). All the controls in this view are encapsulated in a frame. Can be instructed by the Main Display object to highlight a particular item. Commands: Selecting a item in the treeview initiates a display command - this triggers an action in the main form which is passed on to the Main Display object for implementation. Note that clicking a tab is not reported as a command since this has an impact only within the pane and does not change the view elsewhere in the display.
Details Pane	Display: Has a manager object that simply selects a new tab when instructed by the Main Display object. This pane is implemented within a frame that contains a page control that contains other frames that hold the controls needed by each different detail view. Commands: Triggers an action when a tab control is clicked that is handled in the main form. The main form instructs the Main Display object to change the detail view accordingly.
Information Pane	Display: This detail display is managed by an object that displays the current selected view item in a web browser control. This manager object creates the require HTML. The pane is implemented in a frame. Commands: Some view items display links in the web browser that, when clicked, perform some action. This is handled by a command object that both implements the web browser's "external" object and triggers the appropriate action. The action is managed by the main form which calls on the appropropriate object to implement it.
Compile Pane	Display: Displays current compiler details to the user and provides controls that can be used to test-compile a selected unit. If the currently selected view item is not a routine this area displays a message to that effect and hides controls. Commands: Each control in this area is associated with an action that is handled by the main form which in turn calls the appropriate object to handle the action.
Status Bar	Display: Displays status information. Updated via action objects. Commands: No commands issued.
Main Form	Display: Handles the display of GUI widgets that do not form part of the main display - e.g. the splitter bar, the size and location of the main window etc. Any "commands" that are purely concerned with main display items are not necessarily handled by actions but may use event handlers. Several helper objects are created and maintained by the main form. Commands: All commands issued by other GUI components as actions are handled by the main form. Top level logic is handled here to convert the action request into a form that can be handled by some other display or other object. Some simple, none display related actions may be entirely implemented in the main form.

Handling GUI Events

There are several ways in which the user can intiate events in the GUI:

Menu items
Tool buttons
Tab sets in overview and detail panes
Changing selection in tree view
Clicking links in web browser controls

All possible GUI events ultimately result in an Action being triggered. The following schematic shows how CodeSnip responds to events in the GUI and causes actions to be triggered:

Triggering actions is quite straightforward in the case of menu items and tool buttons. They have actions associated with them at design time that are automatically triggered when the menu item or toolbutton is clicked.

For tabs (TTabSet and TPageControl) and the tree view this is not so straightforward since appropriate actions can't be directly associated. Instead events in these controls are handled by event handlers, which ultimately call a method of the "notifier" object (described later).

The web browser controls can also trigger GUI events as a result of the user clicking links or pressing buttons in HTML forms. The web browser's DOM provides an "external" object that can be used to transmit these events to the main application. We define an object that extends the "external" object with methods that can be called from within the browser. The "external" object calls methods of the notifier object in response to these events.

The notifier object has knowledge of various Action objects that can be triggered when the notifier's methods are called. Some of these actions are simple actions, some are standard actions and others are custom actions defined in CodeSnip. The notifier object therefore provides a means for objects that can't natively trigger actions to cause actions to be triggered.

Most actions are handled in OnExecute event handlers in the main form. Some of these simply manipulate some values and then cause a further action to be triggered via the Notifier object. Most lead to the main form implementing the action, either directly or via subsidiary objects. A few standard and custom actions lead directly to the requested command being carried out.

Class Heirachies

Frames

[TFrame]
|
+-- TBrowserBaseFrame
|   |
|   +-- TDetailViewFrame
|   |   |
|   |   +-- TCompCheckFrame
|   |   |
|   |   +-- TInfoFrame
|   |
|   +-- THTMLDlgFrame
|   |   |
|   |   +-- TFixedHTMLDlgFrame
|   |   |
|   |   +-- THTMLTpltDlgFrame
|   |
|   +-- THTMLPreviewFrame
|   |
|   +-- TNewsHTMLFrame
|
+-- TCheckedTVFrame
|   |
|   +-- TSelectSnippetsFrame
|       |
|       +-- TSelectUserSnippetsFrame
|
+-- TMemoPreviewFrame
|   |    
|   +-- TRTFPreviewFrame
|   |
|   +-- TTextPreviewFrame
|
+-- TNewsFrame
|
+-- TPrefsBaseFrame
|   |
|   +-- TGeneralPrefsFrame
|   |
|   +-- THiliterPrefsFrame
|   |
|   +-- TPrintingPrefsFrame
|   |
|   +-- TSourcePrefsFrame
|
+-- TRTFShowCaseFrame
|
+-- TTitledFrame
    |
    +-- TDetailFrame
    |
    +-- TOverviewFrame

Forms

[TForm]
|
+-- TBaseForm
    |
    +-- THelpAwareForm
    |   |
    |   +-- TGenericDlg
    |   |   |
    |   |   +-- TGenericOKDlg
    |   |   |   |
    |   |   |   +-- TCodeExportDlg
    |   |   |   |
    |   |   |   +-- TCompilersDlg
    |   |   |   |
    |   |   |   +-- TEditTextDlg
    |   |   |   |
    |   |   |   +-- TFindCompilerDlg
    |   |   |   |
    |   |   |   +-- TFindTextDlg
    |   |   |   |
    |   |   |   +-- TFindXRefsDlg
    |   |   |   |
    |   |   |   +-- TPreferencesDlg
    |   |   |   |
    |   |   |   +-- TPrintDlg
    |   |   |   |
    |   |   |   +-- TSelectionSearchDlg
    |   |   |   |
    |   |   |   +-- TUserDBEditDlg
    |   |   |
    |   |   +-- TGenericViewDlg
    |   |   |   |
    |   |   |   +-- THTMLViewDlg
    |   |   |   |   |
    |   |   |   |   +-- TAboutDlg
    |   |   |   |   |
    |   |   |   |   +-- TCompErrorDlg
    |   |   |   |
    |   |   |   +-- TPreviewDlg
    |   |   |   |
    |   |   |   +-- TUpdateDlg
    |   |   |
    |   |   +-- TMailingListDlg
    |   |   |
    |   |   +-- TWizardDlg
    |   |       |
    |   |       +-- TBugReportDlg
    |   |       |
    |   |       +-- TCodeSubmitDlg
    |   |       |
    |   |       +-- TRegistrationDlg
    |   |
    |   +-- TMainForm
    |
    +-- TSplashForm
    |
    +-- TWaitDlg

Common Dialogs

[TCommonDialog]
|
+-- [TColorDialog]
|   |
|   +-- TColorDialogEx
|
+-- [TOpenDialog]
|   |
|   +-- [TSaveDialog]
|   |   |
|   |   +-- TSaveDialogEx
|   |       |
|   |       +-- TSaveSourceDlg
|   |
|   +-- TOpenDialogEx
|
+-- [TPageSetupDialog]
    |
    +-- TPageSetupDialogEx

Actions

[TBasicAction]
|
+-- [TContainedAction]
|   |
|   +-- [TCustomAction]
|       |
|       +-- TLinkAction
|
+-- TCompLogAction
|
+-- TEditRoutineAction
|
+-- TRoutineAction
|
+-- TTestCompileAction
|
+-- TViewItemAction

Menus and Menu items

[TPopupMenu]
|
+-- TAbstractWBPopupMenu
|   |
|   +-- TWBNulPopupMenu
|   |
|   +-- TWBPopupMenu
|       |
|       +-- TWBDefaultPopupMenu
|
+-- THistoryMenu
    | 
    +-- TBackHistoryMenu
    |
    +-- TForwardHistoryMenu

[TMenuItem]
|
+-- THistoryMenuItem
|
+-- TWBTempMenuItem