| **Navigation:**  [[welcome to my product .htm|User's Guide and Tutorials]] > Guided Tour of Working in Clarion >====== 6 - Starting the Application ====== | [[lc importing existing data.htm|{{btn_prev_n.gif|Previous page}}]][[welcome to my product .htm|{{btn_home_n.gif|Return to chapter overview}}]][[lc creating a browse.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

** **

**Using the Application Generator**

With the Data Dictionary complete, you now can use the Application Generator to create your application. This chapter shows you:

·How to create the .APP file, which stores all your work for the project.

·How to define the first (Main) procedure to create an MDI application frame, and how to call procedures from the application's menu.

**Starting Point:**

**The Clarion environment should be open, and all dialog windows closed.**

**Creating the application (.APP) file**

1.From the IDE Menu, choose **File** {{blttria.jpg|BLTTRIA.jpg}} **New** {{blttria.jpg|BLTTRIA.jpg}} **Solution, Project or Application**.

The //New Solution, Project or Application// dialog appears.

{{newappproject.jpg|NewAppProject.jpg}}

**2.****Select the ****//Clarion for Windows//**** item in the left ****Categories**** pane, and click or select the ****//Application//**** ****Quick Starts**** as shown above.**

**3.****Verify that the ****Location**** is set to the '****//\Lessons\LearningClarion//**** directory.**

**4.**Type //LCLesson// in the **Name** field.

**5.**Uncheck the **Auto create project subdir **checkbox.

**6.**Press the **Create** button.

The //Application Properties// dialog appears.

1.Type //LCLESSON.DCT// in the **Dictionary File** entry, or select it from the ellipsis button.

2.Clear the **Application Wizard** check box.

This Application Generator lesson will not use any Wizards so that it can demonstrate how to use all the other tools that Clarion provides. We will also use the ABC template chain in this lesson.

{{appprops.jpg|AppProps.jpg}}

3.Press **OK** to close the //Application Properties// dialog.

**Creating the Main Procedure**

The //Application Tree// dialog appears. This lists all the procedures for your application in a logical procedure call tree, which provides a visual guide to show the order by which one procedure calls another. You previously saw it in the Getting Started lessons.

The //Main// procedure is the starting point. The lesson application will be an MDI (Multiple Document Interface) program. Therefore the natural starting point is to define the Main procedure using the Frame Procedure template to create an application frame. A frame is a type of visual program-wide starting point, providing menus, toolbars, and other options.

__**Select the procedure type for Main**__

1.With //Main// highlighted in the //Application Tree// dialog, press the **Properties** {{apppropsbut.jpg|AppPropsBut.jpg}} button.

{{selectproctype.jpg|SelectProcType.jpg}}

2.Choose the **Defaults** tab and highlight //Default MDI Frame// in the //Select Procedure Type// dialog, then press the **Select** button.

The //Procedure Properties// dialog appears. It defines the functionality and data structures for the procedure.

{{mainprocprops.jpg|MainProcProps.jpg}}

3.Press the **Actions** button

4.In the //Main ' Properties// dialog, type //SplashScreen// in the **Splash Procedure** field.

5.Press **OK** to close the //Main ' Properties// dialog.

This names the procedure containing an opening screen that will appear for just a brief period when the user first opens the application.

Usually the first task when creating a procedure is to edit the main window. You can place controls, or if the procedure template has controls already, you can customize them.

The application frame itself never has controls. Windows doesn't allow it. We will, however, customize the window caption (the text that appears on its title bar). Then we will add items to the predefined menu, which is also built into the //Frame Procedure// template, and create a toolbar for the application (a toolbar can have controls).

__**Edit the Main window**__

1.Press the **Window** tab. The Window Editor appears:

{{windoweditor.jpg|WindowEditor.jpg}}

2.Press the **Designer** button shown above. The Window Designer appears. Here are all the tools that allow you to visually edit the window and its controls.

3.Choose **View** {{blttria.jpg|BLTTRIA.jpg}} **Properties** to display the Property Pad (if it is not already present).

You'll notice under the View menu that there are several toolboxes, or pads, that are available'all of these are fully dockable and resizable. This means you can configure your workspace, as you want. Because of this configurability, throughout the rest of the lessons some screen shots taken within the Window Designer may not appear the same as on your computer.

4.CLICK on the window's title bar to make sure it has focus (that is, the white "handles" appear to the right and bottom edge of the window).

5.Type //LCLesson Application// in the **Title** entry of the Property Pad, then press TAB.

This updates the caption bar text in the sample window.

{{apptitle.jpg|AppTitle.jpg}}

**Editing the Menu**

From the Window Designer or Properties Pad, you can call the **Menu Editor**, which allows you to add or edit menu items for the application frame window. As you add each menu item, you can access the **Actions** dialog to name the procedure to call when the user chooses that menu item.

For each new procedure you name for the menu to call, the Application Generator automatically adds a "ToDo" procedure to the Application Tree. You can then define that procedure's functionality, just as you are now defining the application frame procedure's functionality.

When the Application Generator generates the source code for your application, it automatically starts a new execution thread for each procedure you call from the main menu (this is required for an MDI application).

__**Add menu items**__

1.From the Window Designer, click on the menu action bar in your window design. In the Property Pad, click on the **Edit Menu** link as shown here:

{{entermenueditor.jpg|EnterMenuEditor.jpg}}

The Menu Editor appears. It displays the menu in hierarchical form in a list box at the left. The fields at the right allow you to name and customize the dropdown menus and menu items.

This template already provides you with a "standard" menu. It contains basic window commands such as an **Exit** command on a **File** menu, the standard editing **Cut**, **Copy**, and **Paste** commands, and the standard window management commands commonly found in an MDI application.

{{menueditor.jpg|MenuEditor.jpg}}

2.Highlight the //?Paste// menu item (see the illustration above).

The Menu Editor inserts new items immediately below the currently highlighted selection. The menu you'll add will be called **Browse**. It will contain three items: **Products**, **Customers**, and **Orders**. It will appear on the menu bar just before the Window menu.

3.Press the **Add New Menu** button {{newmenu.jpg|NewMenu.jpg}} (or press SHIFT+INSERT).

This inserts a new MENU statement, and its corresponding END statement.

4.Press the Menu Down button {{menudown.jpg|MenuDown.jpg}} to position the MENU inline with the other MENUs.

{{aftermenumove.jpg|AfterMenuMove.jpg}}

5.In the **Text** field in the right hand pane, type //&Browse// in the field then press TAB.

This defines the text that appears on the menu to the end user. The ampersand (&) indicates that the following character (B) is underlined and provides keyboard access (the user can press ALT+B to drop down this menu).

__**Add the first menu item**__

1.Press the **New Item** button {{newmenuitem.jpg|NewMenuItem.jpg}} (or press INSERT).

This updates the list on the left side of the dialog, changing the text of the menu you just added to "&Browse." It adds a new menu ITEM'a command on the dropdown menu'under &Browse.

2.Type //&Customers// in the **Text** field then press TAB.

3.//Type ?BrowseCustomers// in the **Use** field. This is an equate for the menu item so code statements can reference it. The leading question mark (?) indicates it is a field equate label.

{{browsecustomermenu.jpg|BrowseCustomerMenu.jpg}}

4.Right-click on the ITEM just added, and select the **Actions** item from the popup menu.

{{menuactions.jpg|MenuActions.jpg}}

The prompts allow you to name a procedure to execute when the end user selects the **Browse** {{blttria.jpg|BLTTRIA.jpg}} **Customers** menu item.

5.Choose //Call a Procedure// from the **When Pressed** drop list.

New prompts appear to allow you to name the procedure to call and choose options.

6.Type //BrowseCustomers// in the **Procedure Name** field.

This names the "ToDo" procedure for the Application Tree.

7.Check the **Initiate Thread** box.

The //BrowseCustomers// procedure will display an MDI "child" window, and you must always start a new execution thread for any MDI window called directly from the application frame. The **Thread Stack** field defaults to the minimum recommended value.

8.Press **OK** to close the //?BrowseCustomers Prompts// dialog

__**Add the second menu item**__

1.Press the **New Item** {{newmenuitem.jpg|NewMenuItem.jpg}} button.

2.Type //&Products// in the **Text** field and press TAB.

3.Type// ?BrowseProducts// in the **Use **field.

Normally, the next step is to define the action for the menu item'what happens when the end user executes it from the menu. We'll skip over this step for now, for this menu item only. Later, you'll create a procedure by copying it, then attaching it to this menu, just to show you this capability of the Clarion environment.

__**Add the third menu item**__

1.Press the **New Item** {{newmenuitem.jpg|NewMenuItem.jpg}} button.

2.Type //&Orders// in the **Text** field and press TAB.

3.Type //?BrowseOrders// in the **Use **field.

4.Right-click on the ITEM just added, and select the **Actions** item from the popup menu.

5.In the //Actions// dialog, choose //Call a Procedure// from the **When Pressed** drop list.

6.Type //BrowseOrders// in the **Procedure Name** field.

7.Check the **Initiate Thread** box.

8.Press **OK** to close the //?BrowseOrders Prompts// dialog

__**Close the Menu Editor and Window Designer and save your work**__

1.Press the **Save and Close** {{saveclose.jpg|SaveClose.jpg}} button to close the Menu Editor.

This returns you to the Window Designer.

2.Press the **Save and Close **button.

This returns you to the //Window Designer Editor// dialog.

3.Press the **Save and Close** button to close the Window Editor and the //Procedure Properties// dialog.

This returns you to the Application Tree dialog. There are now three new procedures marked as "(ToDo)": //BrowseCustomers//, //BrowseOrders//, and //SplashScreen//. These were the procedures you named in the Menu Editor.

4.Choose **File** {{blttria.jpg|BLTTRIA.jpg}} **Save**, or press the **Save** button {{savebutton.jpg|savebutton.jpg}} on the toolbar.

{{blk2blue.jpg|blk2blue.jpg}}

**Creating the SplashScreen Procedure**

We named a Splash procedure, and now we'll create it.

1.Highlight the //SplashScreen (ToDo)// procedure and press the **Properties** {{propbut.jpg|propbut.jpg}} button.

2.Choose the **Defaults** tab, highlight //Default Splash Window// in the //Select Procedure Type// dialog, then press the **Select** button.

The //Procedure Properties// dialog appears. There's nothing we really have to do to this procedure except accepting all of the defaults.

3.Press the **Save and Close** button.

4.In the Application Tree toolbar, press the **Save** button {{savebutton.jpg|savebutton.jpg}} to save your work.

**Adding an Application Toolbar and Toolbar Controls**

__**Call the Window Designer and create the tool bar**__

1.Highlight the //Main// procedure.

2.RIGHT-CLICK to display the popup menu.

{{procpopup.jpg|ProcPopUp.jpg}}

Notice that this popup menu contains a set of menu selections that match the set of tabs on the top of every //Procedure Properties// window. It also aligns closely with the right hand pane.

This popup menu provides you with direct access to all the Clarion tools that you use to modify existing procedures, so that you don't have to go through the Procedure Properties window every time.

3.Choose the **Window** menu item. The Window Designer Editor opens. If you are not automatically taken there, press the **Designer** button to access the Window Designer.

{{notebox.jpg|NoteBox.jpg}}

You can bypass the Window Designer Editor and load Designer directly, by setting the following Application Options (this dialog can be found in the IDE Tools menu):

{{autodesigner.jpg|AutoDesigner.jpg}}

4.With the Window Designer active, choose **View** {{blttria.jpg|BLTTRIA.jpg}} **Toolbox** from the main IDE Menu (or press CTRL + ALT + X).

5.Locate and highlight the TOOLBAR control in the Toolbox, and DRAG and DROP to the window:

{{toolbar.jpg|Toolbar.jpg}}

This adds the toolbar'always immediately below the menu'to the sample window. You can add any control to your toolbar by CLICKing on a control in the Controls toolbox, then CLICKing in your toolbar.

__**Place the first button**__

If the control toolbox is not present, choose **View** {{blttria.jpg|BLTTRIA.jpg}} **Toolbox** from the Window Designer menu.

1.CLICK on the BUTTON control, drag the mouse to the toolbar design area (not the Designer's toolbar!), just below the upper left corner, and drop to place the button.

{{dropbutton.jpg|DropButton.jpg}}

2.RIGHT-CLICK on the button you just placed, then choose **Properties** from the popup menu. Or you can press the F4 key.

The //Properties// dialog appears.

3.Clear the **Text** property.

{{notebox.jpg|NoteBox.jpg}} Do not use the spacebar to do this! Use the DELETE or BACKSPACE keys.

We'll place images on these buttons, instead of text, to give the application a more modern look.

4.Type //?CustomerButton// in the **Use** property.

This is the field equate label for referencing the button in code. We included the word "Button" for code readability.

5.Set the **Flat** property to TRUE.

{{tipbox.jpg|TipBox.jpg}}

You can simply click on the Flat property, and it will toggle the TRUE/FALSE values!

{{flatprop.jpg|FlatProp.jpg}}

6.Drop down the **Icon** property, scroll to the bottom and CLICK on //Select File....//.

The //Select Icon File// dialog appears.

7.Select //GIF Files// from the **Files of type** drop list.

8.Select the //CUSTOMER.GIF// file, then press the **Open** button.

{{iconprop.jpg|IconProp.jpg}}

9.Type //Browse Customers// into the **Tip** property.

This adds a tool tip to the button that will display whenever the mouse cursor hovers over the button.

10.Expand the AT property in the Properties Pad, and then set the **Default** property to //False// for both **Width** and **Height**.

11.Set the **Width** to //16// and **Height** to //14//.

{{positionprop.jpg|PositionProp.jpg}}

12.Near the bottom of the Property Pad, click on the Actions link:

{{actionslink.jpg|ActionsLink.jpg}}

13.Choose //Call a Procedure// from the **When Pressed** drop list.

14.Choose //BrowseCustomers// from the Procedure Name drop list.

This is the procedure name you typed for the Browse {{blttria.jpg|BLTTRIA.jpg}} Customers menu item. Pressing the button will call the same procedure. Often, a command button on a toolbar serves as a quick way to execute a menu command.

15.Check the **Initiate Thread** box.

16.Press the **OK** button.

__**Place the second button**__

If the control toolbox is not present, choose **View** {{blttria.jpg|BLTTRIA.jpg}} **Toolbox** from the Window Designer menu.

1.CLICK on the BUTTON control, drag the mouse to the toolbar design area (not the Designer's toolbar!), right next to the first button, and drop to place the button.

A button appears, labeled "button2."

{{button2.jpg|Button2.jpg}}

2.RIGHT-CLICK the button you just placed, then choose **Properties** from the popup menu.

3.Clear the **Text** property.

4.Type //?ProductsButton// in the **Use** property.

5.Set the **Flat** property to TRUE.

6.Drop down the **Icon** property, scroll to the bottom and CLICK on //Select File....//.

7.Select //GIF Files// from the **Files of type** drop list.

8.Select the //PRODUCTS.GIF// file, then press the **Open** button.

9.Type //Browse Products// into the **Tip** property.

Normally you attach an action to the button at this point. Skip this step for now, for this button only. Later, we'll copy a procedure, then call it at the point in the generated source code which handles what to do when the end user presses the button to demonstrate using embed points.

__**Place the third button**__

If the control toolbox is not present, choose **View** {{blttria.jpg|BLTTRIA.jpg}} **Toolbox** from the Window Designer menu.

1.CLICK on the BUTTON control, drag the mouse to the toolbar design area (not the Designer's toolbar!), right next to the second button, and drop to place the button.

2.RIGHT-CLICK on the button you just placed, then choose **Properties** from the popup menu.

3.Clear the **Text** property.

4.Type //?OrdersButton// in the **Use** property.

5.Set the **Flat** property to TRUE.

6.Drop down the **Icon** property, scroll to the bottom and CLICK on //Select File....//.

7.Select //GIF Files// from the **Files of type** drop list.

8.Select the //ORDERS.GIF// file, then press the **Open** button.

9.Type //Browse Orders// into the Tip property.

10.Near the bottom of the Property Pad, click on the **Actions** link.

11.Choose //Call a Procedure// from the **When Pressed** drop list.

12.Choose //BrowseOrders// from the **Procedure Name** drop list.

This is the procedure name you typed for the **Browse** {{blttria.jpg|BLTTRIA.jpg}} **Orders** menu item.

13.Check the **Initiate Thread** box.

14.Press the **OK** button to close the //Actions// dialog.

__**Position and align the buttons**__

The Window Designer has a set of alignment tools that easily allow you to line up and resize your window controls.

1.With the //Orders// button still selected, CTRL+CLICK on the //Customers// button.

This gives both buttons "handles" and the Customers button has the Red handles that indicate it has focus.

CTRL+CLICK is the "multi-select" keystroke that allows you to perform actions on several controls at once. Once multiple controls are selected, you can move them all by dragging on any one of the selected controls, or you can use any of the Alignment menu's tools on the entire group.

2.With both buttons still selected, CTRL+CLICK on the //Products// button.

Now all three buttons have "handles", and the Orders button has the white handles that indicate it has focus and is the "key control" for the alignment actions.

3.RIGHT-CLICK and choose **Format > Align > Tops** from the popup menu.

{{aligntops.jpg|AlignTops.jpg}}

When you have multiple controls selected, RIGHT-CLICK displays an alignment popup menu instead of a single control's popup menu. This action aligns all three buttons with the top of the //Products// button.

4.RIGHT-CLICK and choose **Format > Horizontally Spacing > Make Equal** from the popup menu.

{{makeequal.jpg|MakeEqual.jpg}}

This spaces all three buttons apart equally. Make sure they're close together, so there's room for what's coming next!

__**Add the Frame Browse Control buttons**__

1.Close all opened pads at this time, so you have plenty of room to work.

2.From the IDE Menu, choose **View** {{blttria.jpg|BLTTRIA.jpg}} **Control Template.**

The //Control Template// pad appears.

3.Highlight (click on) the //FrameBrowseControl// template, then drag and drop just to the right of the 3rd toolbar button.

{{framebrowsecontrol.jpg|FrameBrowseControl.jpg}}

The thirteen Browse control buttons appear on the toolbar. You've already seen these buttons on the applications you created in the Getting Started topic. These buttons can control the scrolling and update procedure call behavior of the Browse procedures you'll create (later in the lessons).

__**Close the Window Designer and save your work**__

1.Press the **Save and Close **{{saveclose.jpg|SaveClose.jpg}} button.

This returns you to the //Window Designer Editor// dialog.

2.Press the **Save and Close** button to close the //Procedure Properties// dialog.

3.Choose **File** {{blttria.jpg|BLTTRIA.jpg}} **Save**, or press the **Save** button {{savebutton.jpg|savebutton.jpg}} on the toolbar.

**Testing an Application under Development**

1.With the Application Tree dialog open, **Generate Source**, and **Build** and **Run** your application by pressing the **Start without Debugger** button (shown below):

{{gse4c.jpg|GSE4C.jpg}}:

The Application Generator generates the source code, displaying its progress in a message window, procedure by procedure.

Next, the **Output** window appears, showing you the progress of the build as the compiler and linker do their work.

Then your Application window appears.

{{tutorialpartone.jpg|TutorialPartOne.jpg}}

2.Press one of the buttons on the toolbar, or choose one of the items on the **Browse** menu.

A message box appears that says, "The Procedure (//procedure name//) has not been defined":

This capability allows you to incrementally test your application, whether you have designed all the procedures or not.

You'll fill in their functionality, starting in the next topic (Creating a Browse).

3.Press the **OK** button to close the message box.

4.Choose **File** {{blttria.jpg|BLTTRIA.jpg}} **Exit** to close the //LCLesson// application.

Throughout the rest of this lesson, feel free to Make and Run the developing application whenever the lesson instructs you to save the file.

**Look at the Generated Source Code**

Let's take a quick look at what the Application Generator has done for you. The whole purpose of the Application Generator (and its Templates) is to write Clarion language source code for you. There is no "magic" to what the Clarion toolset does to create applications'it all goes back to the Clarion programming language.

1.With the Application Tree dialog open, Change the **Tree Mode** drop list to //Module//.

This changes your view of the application from the logical procedure call tree to the actual source code modules generated for the application.

{{moduletreeview.jpg|ModuleTreeView.jpg}}

2.Highlight the //LCLesson.CLW// module, RIGHT-CLICK to display the popup menu then CLICK on **Module**.

This takes you right into the Text Editor, looking at the last source code you generated (the last time you pressed the Run button). Any changes you made since the last time you generated code will not be visible here.

The //LCLesson.CLW// file is the main program module for this application, containing the Global data declarations and code. Don't be intimidated looking at all this code. After you've finished this lesson, you can go on to the //Introduction to the Clarion Language// lesson at the end of the Learning Clarion topics and become more familiar with the Clarion Language (it's actually very straight-forward).

3.When you have finished looking at the code, choose **File** {{blttria.jpg|BLTTRIA.jpg}} **Close** {{blttria.jpg|BLTTRIA.jpg}} **File** to exit the Text Editor and return to the Application Generator (You can also simply press the Close button {{closerbut.jpg|CloserBut.jpg}} in the source window).

{{notebox.jpg|NoteBox.jpg}}

Be sure NOT to choose **File** {{blttria.jpg|BLTTRIA.jpg}} **Exit**, otherwise you'll exit Clarion for Windows completely.

4.With the Application Tree dialog open, Change the **Tree Mode** drop list to //Procedure//.

This changes your view of the application back to the logical procedure call tree.

5.Highlight the //Main (Frame)// procedure, RIGHT-CLICK to display the popup menu, then CLICK on **Module**.

This takes you into the Text Editor again, looking at the last source code you generated for the Main procedure. Again, any changes you made in the Application Generator since the last time you generated code will not show up in this code.

You may have noticed that right below the //Module// selection was another called //Source//. Do not confuse these two, they do very different things. We will demonstrate the //Source// selection later in the lessons.

If you do make any changes to this code, you actually can compile and run the program to see what effect the changes make, however, your changes will be lost the next time you generate source code. Therefore, it is not a good idea to make any changes here.

6.When you have finished looking at the code, choose **File** {{blttria.jpg|BLTTRIA.jpg}} **Close** {{blttria.jpg|BLTTRIA.jpg}} **File** to exit the Text Editor and return to the Application Generator. You can also simply press the **Close** button {{closerbut.jpg|CloserBut.jpg}} in the source window.

**OK, What Did I Just Do?**

Here's a quick recap of what you just accomplished:

| {{blueck.jpg|blueck.jpg}} | You created a new .APP file'without using a wizard. |
| {{blueck.jpg|blueck.jpg}} | You created an application Frame procedure'without using a wizard. |
| {{blueck.jpg|blueck.jpg}} | You created a menu in your application frame. |
| {{blueck.jpg|blueck.jpg}} | You created a splash screen procedure for your application. |
| {{blueck.jpg|blueck.jpg}} | You created a toolbar under your application's main menu and placed iconized, flat buttons on it. |
| {{blueck.jpg|blueck.jpg}} | You used Clarion's resize and alignment tools to adjust your screen design. |
| {{blueck.jpg|blueck.jpg}} | You used a Control Template to populate your toolbar with a set of standard navigation buttons. |
| {{blueck.jpg|blueck.jpg}} | You compiled and ran your work-in-progress to test its functionality. |

In the next lesson, we'll add a Browse procedure to the application.

[[lc creating a browse.htm|Click here to jump to the next lesson]]