Form Launching

*** With the release of Frameworks 16, these instructions have been depreciated.  ***

There are three primary methods for launching application forms from the MDI Frame: the hierarchical menu, the button toolbar, and the launch bar. The following exercises will guide you through adding a (theoretical) new form to the MDI Frame so that it can be launched from all three of these techniques. This article may seem long at first, but most of it is filled with screenshots and reference material. After going through this once, you will find it relatively easy to do it again for your next form.

Creating a New MDI Child

The form designing article provides tips on creating new application forms (usually in the form of MDI Children). If you have not prepared a new form yet then take a few minutes to start one. It does not have to be complete, just enough to launch for testing purposes. For demonstration purposes we have created a test application, MOVIES, and an MDI Child form, DBW_MOVIES, that we will use in this article. Our data comes courtesy of IMDb. Here is what our sample form looks like:

material. After going through this once, you will find it relatively easy to do it again for your next form.

Modifying FRW_MAIN

The first two methods for launching an application form involve modifications to FRW_MAIN. As explained in the form designing, this will first require that FRW_MAIN be copied into the local application. The easiest way to do this is to open the inherited FRW_MAIN with the Form Designer, make a minor change, and then perform a "Save As" request.

In the Form Designer, FRW_MAIN appears differently from when it is launched:

This is intentional. Since the layout of FRW_MAIN will always be dynamic, and subject to the security credentials of the end user, the design layout was chosen for ease of management. One of the core SRP FrameWorks stored procedures, Set_Frame(), will be used to manage the control layout during runtime.

Adding a new MDI Frame Menu Item

Accessing application features from a menu system is pretty standard. Developers can take the menu in FRW_MAIN and create any number of items that will be used to launch MDI Child forms. The MDI Frame Menu is generally the best option for organizing large numbers of application features that might be available to the end user.

Configuring the Menu with the Menu Builder

Updating the menu in FRW_MAIN is handled through the Menu Builder. For our example, we added a menu item and a separator to the existing top-level Sample menu:

Viewing the new MDI Frame Menu Item

When FRW_MAIN is launched, our new menu item appears like this:

We will not be using the Menu Script or QuickEvent handlers to launch our MDI Child window. Instead, we will rely on SRP FrameWorks' advanced event handling to automatically call our commuter module: FRW_MAIN_EVENTS. Later on in this article we will document how to properly update the commuter module. For now, we just need the menu item as a place holder.

Adding a new MDI Frame Toolbar Button

FRW_MAIN provides developers with a standard toolbar that provides typical functionality such as saving the active document, copying text to the clipboard, and printing the form. There is also space for custom buttons, which gives the developer another place to give end users access to application features. The MDI Frame Toolbar is an ideal location for buttons that launch an application's most commonly used MDI Child forms.

These buttons are added to the form using the Form Designer. The pre-existing toolbar buttons are seen as a stack of non-descriptive [SRP_Button_Control|SRP Button] controls. Eventually the five buttons which launch the sample forms can be re-purposed or removed. When adding a new button, we recommend copying an existing one and moving it underneath the existing controls. Here is what our FRW_MAIN looks like after we added a new button to launch our DBW_MOVIES form:

Configuring the Toolbar with the Frame Manager

Adding another SRP Button control to FRW_MAIN is not enough. We also must use the Frame Manager (i.e., launch the DBW_FRAME_MANAGER form from the Application Manager) to configure this new button on the toolbar. After the Frame Manager is running, click on the Set Frame Settings tab:

The following legend documents how this part of the Frame Manager should be used:

We decided to create a new group for our Movies button. This is what the new row in the Frame Manager looks like:

Viewing the new MDI Frame Toolbar Button

Now that our new toolbar is added to FRW_MAIN and has been properly configured, we can launch the MDI Frame and see what our new toolbar looks like:

Just like the new menu item we added, the Menu Script and QuickEvent handlers will be set aside and the FRW_MAIN_EVENTS commuter module will be used instead. This will be explored later in this article.

Adding a new MDI Launch Bar Item

Many modern applications provide an alternative to the horizontal toolbar by creating a vertical display of clickable items. We call this the Launch Bar:

Configuring the Launch Bar with the Frame Manager

Unlike adding a new menu item or toolbar button, we will not be modifying FRW_MAIN for this task. Instead, we will again launch the Frame Manager (i.e., the DBW_FRAME_MANAGER form) and click on the Launch Bar Settings tab:

As you can see, a view of the MDI Frame's Launch Bar appears in this tab. We use this part of the Frame Manager to add, remove, or modify Launch Bar groups and items. A full explanation of this tab will presented in a different article. For now, just follow these steps to add the new MDI Child to the Launch Bar:

1. Click on the Add Group command button. This should add a new group labelled Group 6 to the Launch Bar and underneath this group will be a new item labelled Item 1.
2. Click into the Caption property cell and change "Group 6" to something meaningful. We will enter User Forms:
   
   
    
3. Click on the item labelled "Item 1" in the Launch Bar display. This should update the "Caption" property cell with the value "Item 1"
4. Click into the Caption property cell and change "Item 1" to something meaningful. We will enter Movies
5. Click into the Proc. Type property cell and use the dropdown to select MDIChild Window. In the Proc. Name property cell use the dropdown to select the form you are adding. We will select DBW_MOVIES:
   
   
    
6. If you are feeling a little adventurous, click on the newly created User Forms group in the Launch Bar display and drag it higher, such as just above he Reports group.

Viewing the new MDI Frame Launch Bar

We can now launch our MDI Frame one more time to see the results of our work:

Since the functionality of the Launch Bar is defined by the Frame Manger, rather than the FRW_MAIN_EVENTS commuter module, you can click on the Launch Bar item now to see your form getting launched.

Modifying FRW_MAIN_EVENTS

While SRP FrameWorks does not prevent forms from using Script or QuickEvent handlers, the intent behind its advanced event handling technology is to eliminate them. We believe that once you become familiar with handling all events from within a commuter module function without the chore of making a connection for each event handler within the Form Designer, you will never want to handle events any other way.

We will dissect the standard SRP FrameWorks commuter module in a different article. For now, we will make some simple modifications to FRW_MAIN_EVENTS in order to allow our new menu item and toolbar button to launch our MDI Child window.

As with many typical routines designed to be used as a commuter module, the first main section of code routes the event request using a Begin/End Case statement block. SRP FrameWorks commuter modules automatically populate key variables such as Control and Event with the appropriate values. SRP FrameWorks commuter modules typically route events to GoSub labels naming with a Control.Event format. Thus, a CLICK event for the PUB_OK button would route to the CLICK.PUB_OK label within the commuter module.

Generally, commuter modules detect the control name first and then group all related events underneath it like this:

Case Control EQ 'PUB_OK'

    Begin Case
        Case Event EQ 'CLICK'               ; GoSub CLICK.PUB_OK
    End Case

Case Control EQ 'EDL_NAME'

    Begin Case
        Case Event EQ 'GOTFOCUS'            ; GoSub GOTFOCUS.EDL_NAME
        Case Event EQ 'LOSTFOCUS'           ; GoSub LOSTFOCUS.EDL_NAME
        Case Event EQ 'CHANGED'             ; GoSub CHANGED.EDL_NAME
    End Case

Within FRW_MAIN_EVENTS, certain events are detected first and then all related controls are grouped together. This is done when these controls are unlikely to have other event handlers, so it becomes more economical to organize them this way:

Case Event EQ 'OnClick'

    Begin Case
        Case Control EQ 'PUB_TB_NEW'        ; GoSub OnClick.PUB_TB_NEW
        Case Control EQ 'PUB_TB_OPEN'       ; GoSub OnClick.PUB_TB_OPEN
        Case Control EQ 'PUB_TB_SAVE'       ; GoSub OnClick.PUB_TB_SAVE
        Case Control EQ 'PUB_TB_DELETE'     ; GoSub OnClick.PUB_TB_DELETE

This design makes it very easy to add event handlers. In fact, event handlers can be added, modified, or removed at will even while the form is still running. No more closing the form, making changes in the Form Designer, recompiling, and running the form all over again.

In order to enable our new menu item and toolbar button to work, we will make the following additions to FRW_MAIN_EVENTS:

1. Under the Case EventType EQ 'MENU' branch add the following:

   Case Control EQ 'MOVIES'  ; GoSub MENU.MOVIES

2. Under the Case Event EQ 'OnClick' branch add the following:

   Case Control EQ 'PUB_TB_MOVIES'  ; GoSub OnClick.PUB_TB_MOVIES

Of course, you should replace references to MOVIES with the name that you choose for your controls. Now that we have updated our event router (aka event dispatcher) to identify our new MENU and OnClick events, we need to add the relevant labels and necessary code within the main body of FRW_MAIN_EVENTS. We will add the following:

MENU.MOVIES:
    Child = Start_MDIChild('DBW_MOVIES', @Window)
return

OnClick.PUB_TB_MOVIES:
    Child = Start_MDIChild('DBW_MOVIES', @Window)
return

Clearly the code for both event handlers has been duplicated. This means any changes made to one handler should be made to another. We can eliminate the need to change the code in both places simply by modifying one event handler to call the other, like this:

OnClick.PUB_TB_MOVIES:
    Send_Event(@Window : '.MENU.SAMPLE.MOVIES', 'MENU')
return

Launching our New MDI Child

If everything has been done correctly then we can launch FRW_MAIN and click on our new menu item, toolbar button, and launch bar item. Our MDI Child form should appear.

As your applications begins to evolve, you will likely need to do more than launch MDI Child forms. Hopefully this exercise has given you a foundation from which you can do other things.