| **Navigation:**  [[welcome to my product .htm|User's Guide and Tutorials]] > The Application >====== Lesson 1 - Anatomy of an Application ====== | [[application generator intro.htm|{{btn_prev_n.gif|Previous page}}]][[welcome to my product .htm|{{btn_home_n.gif|Return to chapter overview}}]][[lesson 2 the power of the application wizard.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

**Introduction**

Once you have completed the preliminary design of the data dictionary, the next step is to decide what needs to be done with the data.

**Information will need to be entered so that records can be added to data tables. Existing information will need to be revised or deleted and reports will need to be printed. In order to accomplish these tasks, the computer needs to be given instructions. These instructions must be very explicit. The computer must be told every step to take and in what order to take each step.**

With a traditional programming language, it is the job of the programmer to write the instructions that make up a program. With Clarion, the necessary statements of the programming language are generated for you. You will denote the major tasks to be done, describe the way you want those tasks to work, and how your screens and reports will appear. Clarion will write the program, creating the language statements needed to do the job in the most efficient manner.

The major tasks to be performed by the program (display a screen, print a report, etc.) are called **procedures**. Procedures consist of a number of instructions. When these instructions are being performed, we say that the procedure is executing. A procedure returns when all instructions have been executed.

Procedures must be named. A procedure begins to execute when an instruction calls the procedure by its name.

Certain types of procedures are common to almost all programs. Most programs consist primarily of menus, scrolling lists, data entry screens, and reports. Clarion supports these and many other procedure types.

Programs are created in the Application Generator by choosing a procedure type which most closely matches your requirements and then customizing the default menu, screen, or report, and/or by defining data, or by creating formulas and embedded source. Procedures "call" other procedures and are "connected" to them in a "building block" approach that eventually results in a complete program. The Application Generator stores program and procedure characteristics in Application (.APP) files.

{{ag1.jpg|AG1.jpg}}

In addition, there are **code**, **control**, **extension **and **wizard **templates, which allow you to virtually customize and quickly generate any of the built-in procedure templates, bundled with Clarion. For example, a form may now have a List Box, by choosing a "Browse Box" control template. Validation of a field or control can be added anywhere by adding the appropriate code or extension.

**Creating the Application (.APP) File**

The first step in creating a new application (after creating a Data Dictionary) is to create an application (.APP) file. The application file holds the procedure specifications, data declarations, and other properties you define for your application'it contains everything necessary to generate source code, and then make an executable program.

All applications are contained within a Clarion **Solution** file (*.SLN). A Solution file contains all of the information needed to build the application into a distributable executable file or library for use with other executables. Solutions can also hold multiple applications, but that topic is covered in a later lesson in this section.

{{tipbox.jpg|TipBox.jpg}}

You may want to create a new folder for each application you develop because whenever you open an application (.APP) file, Clarion uses the directory in which the file resides as the working directory.

1.Optionally, in Windows Explorer, choose **File** {{blttria.jpg|BLTTRIA.jpg}} **New** {{blttria.jpg|BLTTRIA.jpg}} **Folder**, type a folder name then press **OK**.

**This creates a working folder for your application. You can also let the Clarion Project System create the folder for you.**

2.Start Clarion and choose **File** {{blttria.jpg|BLTTRIA.jpg}} **New** {{blttria.jpg|BLTTRIA.jpg}} **Solution, Project or Application**.

This opens the //New Solution, Project or Application// dialog.

{{ag2.jpg|AG2.jpg}}

This dialog allows you to type in the basic information the Project System needs to create a new Clarion for Windows project file (.CWPRJ) and solution file (*.SLN for you).

| **Categories** | Select a valid category. To create a Win32 application, select the //Clarion for Windows// category. |
| **Quick Starts** | Specify the type of project that you wish to create. In Clarion for Windows, the Quick Starts available are hand coded DLL, EXE, or Library projects, or //Applications// (from scratch or from an existing TXA file). A TXA file is an application in a special text format. Select the //Application// Quick Start here. |
| **Name** | Type in a project name which displays at the top of the Tree List in the Project View. This is normally the name of your target output by defualt, but your target can later be modified. |
| **Location** | Type in (or select with the Browse for Folder dialog after pressing the ellipsis button) the location where the project will be created. |
| **Create directory for Sources** | Check this box to specify a subdirectory with the project name that will be created at the **Location** you specified. |
| **Auto create project subdir** | Check this box to autocreate a project folder that uses the project Name and Location specidfied. For example, if the name of the project is //Orders// and the Location is //C:\Example, //a sub-folder named //Orders// will be created in the //Example// folder. |

**3.****After selecting the appropriate options above (make sure you have selected the ****Application**** ****//Quick Start//****), press the ****Creat****e button.**

This opens the //Application Properties// dialog where you define the basic files and properties for the application.

{{ag3.jpg|AG3.jpg}}

4.In the **Application File** entry, optionally press the ellipsis (...) button to redefine the pathname for your .APP file.

5.Type a name for the .DCT file in the **Dictionary File** entry, or press the ellipsis (...) button to select the dictionary file from the //Select Dictionary// dialog.

See the previous [[dictionary editor.htm|lesson]] for information on creating your application's data dictionary.

{{tipbox.jpg|TipBox.jpg}}

The Application Generator does not require a data dictionary to generate an application if you clear the **Require a dictionary** box in the //Application Options// dialog. See [[lesson 3 the application generator environment.htm|Lesson 3 - The Application Generator Environment]] for more information.

6.In the **First Procedure** entry, name the application's "supervisor" procedure if you do not wish to use the default name of "Main".

7.Choose the **Destination Type** from the drop-down list.

This defines the target file for your application. Choose from Executable (.EXE), Library (.LIB), or Dynamic Link Library (.DLL).

Choosing Dynamic Link Library (.DLL) enables the **Export Procedure** prompt in the //Procedure Properties// dialog (see Setting Procedure Properties) and the Export all file declarations prompt in the [[lesson 11 global application properties.htm|Global Properties]] dialog.

{{tipbox.jpg|TipBox.jpg}}

Using LIBs or DLLs to modularize and organize larger applications can provide substantial savings in development and maintenance costs: compiling and linking only a portion of a large application saves development time, and calling a set of common functions from a single source means maintaining only one set of code.

You may want to develop a portion of an application as an .EXE, then remake it as a .DLL when complete. See [[advanced topics.htm|Advanced Topics - Development and Deployment Strategies]] for more information.

{{tipbox.jpg|TipBox.jpg}}

Setting the Project's Target Type is equivalent to setting the Application's Destination Type and vice versa. See [[project system lesson.htm|Project System]] for more information.

8.Type a name for the application's .HLP file in the **Help File** field, or use the ellipsis (...) button to select one from the //Select Help File// dialog.

**If you specify a help file in the current directory, the application looks for the help file in the current directory, then the system directory, then the system path. The full path is not stored.**

However, if you specify a help file in another directory, a full path is established and the application looks for the help file by the full pathname.

You are responsible for creating a Windows Standard .HLP file that contains the context strings and keywords that you enter as HLP attributes for the application's various controls and dialogs. There are many third party products that help you do this.

9.Choose the **Application Template** type.

**Accept the default (ABC), or press the ellipsis (...) button to select from another template set. The Application template controls source code generation.**

10.Choose the **ToDo Template** type.

**Accept the default (ABC), or press the ellipsis (...) button to select from a third party template set. The ToDo template controls source code generation.**

11.Clear the **Application Wizard** box by clicking on it.

Checking this box causes the Application Generator to create an entire working application based on the data dictionary you selected. In the next topic lesson, we will build an application using the Application Wizard. For now, we'll examine the Application Tree when completing the next step.

12.Press the **OK** button.

** **

**Clarion creates the .APP file, then displays the Application Tree dialog for your new application. When you make a new application, you only have one procedure defined for you. This procedure is a ****//ToDo//**** type, which means you may choose what type of procedure to create. You do this by pressing the ****Properties**** button.**

** **

{{ag4.jpg|AG4.jpg}}

** **

**The Application Tree dialog provides six different views of your application. The Procedure view displays all application procedures in hierarchical order, nesting each procedure under its calling procedure.**

{{ag5.jpg|AG5.jpg}}

__**Adding Procedures to your Application**__

A //procedure// is a series of Clarion language statements (source code) which perform a task. A //Procedure template// is an interactive tool that (with the help of Clarion's development environment) requests information from you, the developer, then generates a custom procedure for just the task you specify.

A Procedure as stored in a Clarion application (.app) file, is really a specification that the development environment uses to generate the procedure source code. The specification includes the Procedure template, your answers to its prompts, the WINDOW definition, the REPORT definition, local data declarations, embedded source code, etc.

Your application's supervisor procedure is called "Main" by default. You can name this procedure anything you want, but this chapter refers to it as "Main." All other procedures branch from "Main"'one procedure can call another.

**Application Tree**

The hierarchical tree controls (or outline controls) in the Application Tree dialog illustrate how the procedures branch from "Main" and from each other. This provides a schematic diagram of your program's logical structure.

{{tipbox.jpg|TipBox.jpg}}

An {{embedmark.jpg|Embedmark.jpg}} icon means the procedure contains embedded source code.

The Application Generator adds a procedure to the Application Tree whenever you press the insert key, or add a menu item, a toolbar command, or a code template that calls a procedure. Each new procedure is marked "To Do." When you "fill in" its functionality, the Application Generator replaces the "To Do" with your description.

**Defining the Procedure Type**

Once you add a "ToDo" procedure to the Application Tree, the next step is to define its type from the choices available in the //Select Procedure Type// dialog. The choices available correspond directly to the Procedure templates in your template registry. See Procedure Templates in the Template Guide for more information on the Procedure templates in this package.

·To open the //Select Procedure Type// dialog, select any "ToDo" procedure in the Application Tree dialog, then press the **Properties** button, or double-click on the "ToDo" procedure.

{{ag6.jpg|AG6.jpg}}

**Wizards**

Template Wizards are the most powerful design tool within the Application Generator. Here, you can select a base procedure (Browse, Form, Report, etc.) or a whole application, and then fine tune the wizard prompts and options to produce a near perfect application or procedure that fits your specifications.

The next lesson will focus on the Wizards in more detail

**Defaults**

The Defaults tab allows you to select from a wide variety of pre-defined structures and functionality. Based on the type of default you select, the template procedure associated with it is automatically attached upon your selection.

**Templates**

This dialog lets you choose a procedure template, adding functionality to any new or "To Do" procedure in the Application Tree

CLICK on a procedure template from the list, then press the Select button. Once you select a procedure type, you can customize it using its Procedure Properties dialog.

If you add third party, or your own customized templates to the Template Registry, they also appear in the list.

If you must change the procedure type later, go to the Application Tree, highlight the procedure, then press the **Properties **button.

{{ag7.jpg|AG7.jpg}}

Press the ellipsis button as shown above. The //Select Procedure Type// dialog appears so you can select another procedure type. If the new procedure type doesn't support some of the structures'such as menus'that you defined in the previous procedure type you may "orphan" the previously defined structures. Therefore, be cautious when changing procedure type.

This concludes this lesson.

**Next:** [[lesson 2 the power of the application wizard.htm|Lesson 2 - The power of the Application Wizard]]