Linking Template Definitions to C functions
An important feature of the program is its facility to associate C functions with icons based on the icon name. Any Template editor can be used to set the icon name in the icon's validation string using the (unofficial) 'N' validation
code. The functions are placed in a file in a C source file directory inside the application. Each template file has its own directory with the same name as the template file, and the c source directory is placed inside this. All template directories for an application are placed in a directory named 'FormSrce' inside the application. The functions are systematically named, in the form :
<appname>_<Template_File_Name>_<Template_Name>_<icon_name>_<function_type_suffix>.
The !bar example application in the Examples directory illustrates this. For example the barw window in the bartmpl template file has a 'nudger icon' which uses a sprite which is a small upward facing arrow head, and has a validation string of Sup,pup;R5.
The name can be tacked onto the end of the string - Sup,pup;R5;Nbar:bartmpl/barw.nudgeup. To see this, first make sure you have a text editor that can handle external edit requests loaded - !StrongEd, or !Zap are suitable, then, load !DrWimpC and drag the !bar application icon in the examples directory to the !DrWimpC icon on the iconbar, and load the template file bartmpl from the !DrWimpC main menu item (Template Files item). Use the adjust mouse button to keep the menu open, and navigste to the Templates item, also on the main menu, to get a list of templates in the template file. Click on the item for the barw template to load it. Now click on the up arrow icon to load the barw template containing the icon definition and click on it to cause a source file named barw to be loaded into the editor with the edit caret at the function definition for the function associated with the up arrow icon.
You can edit and save this file as usual. This type of function is called in response to mouse clicks on the icon automatically by theDrWimpC library. Other function types can be defined to 'show', 'input' and accept key presses in an icon. The mouse click and key press functions are called automatically, however, the show and input functions are not - it is left to each application to determine when to accept the input or key press and call each defined function as appropriate or call them all at once by using the DrWimpC library calls drw_show_icons, or drw_input_icons. This allows great flexibility in how an application handles the display and input of window data. Library calls are also provided to obtain an icon's number from its name for use in a program.
The idea in using icon names is twofold. Firstly, to associate the name with a function, as just described, and secondly to avoid the limitation of using icon numbers in program code to the effect that the template can be edited, when icon numbers may change, without affecting the source code (or function names which would be the case if icon numbers are used.). A set of 'registration' functions are automatically generated by !DrWimpC - source placed in a 'FormReg' directory in a simlar way to the 'FormSrce' directory. and called when a template is first loaded to associate the icon names in the template definition with the functions to be called , as described. Then, when each window instance is loaded, the functions are associated with it. A data handle (of type void *) may be optionally associated with each window instance and passed to the called function so that it can act on data defined in the application for use in carrying out the icon's action.
When you come to compile the application code using one of the application sub menu items 'Build', or 'Make', the makefile to be used in the compilation is automatically generated, and the code in the 'FormSrce' and 'FormReg' directories is automatically included. In addition, your own code can be associated with and called by the template functions, by storing it in your own source files in the c directory for the template files in the FormSrce.<TemplateFileName> directory. You can see this in the case of !bar by opening the directory !bar.FormSrce.bartmpl.c directory.There you will find a file called 'bartfns' which contains the support functions bar_increase, bar_decrease and others which are called by the function defined for the nudgeup (and nudgedown) icons.
The code for the 'FormSrce' and 'FormReg'directories is collected into libraries - one for each template file and one for the associated template registration functions. This means that this code is potentially reusable in other applications just by including the libraries in the compilation process of other applications, and DrWimpC and !DrWimpC contain facilities to achieve this.
There are also a couple more things these applications must do during template design, and application load time initialisation for this to work. The example application Examples.!bar2 illustrates this by attaching two pane windows created from the !bar.bartmpl barw template definition, and four groups of icons defined in its main window which are identified with the template functions for the !bar.bartmpl template file by using the full icon naming system - the names must identify the application, template file and window definition that from which they get their template functions. For now, using the full name isthe preferred method to always ensure uniqueness of the resulting function names.
There are over a hundred template function types. Except for the mouse click function type, each type has its own three letter suuffix added to the function name derived from the application, template file, template and icon name elements, with each element separated by an underline. The mouse click function type has no suffix. One important function type is the initialisation type. This type is used to indicate that the icon that is associated with the initialisation function is used to identify a group of icons whose extent is within this icon's extent in the tempate definition, and have the same application, template file and template name in their icon name.
This effectively, provides a means of defining 'Template Objects' which once defined, can be reused with their associated functionality in other applications. The template definitions can be supplied either separately, or with applications in a specifically named repository inside !DrWimpC which has an associated system variable, <DrWimpC$Repositroy>. This repository is a directory named 'Repository' inside !DRWDEF which is usually placed in Boot:Resources so that each application using them can load the templates without the need for hard coding the location of the repository containing the templates. The variable will also identify
the location of the supporting code library at compile time. E.g. the !bar2 application uses the bar templates (bartmpl) defined in !bar, and consequently uses the libraries in the !bar.FormSrce for the templates, so the !bar.!boot file has a call to an obey file !SetVars in the !bar application that defines the bartmpl$dir sustem variable. There are several pages on the web site that give more detail about defining and using template functions and objects and the DrWimpC Repository and their reusability particulalry as shared libraries.
This means that to compile and link !bar2, the !bar must have been seen by the filer, so that the !bar.!boot file is run. the method used in these examples to reuse templates and their associated code can be similarly used in your own DrWimpC applications. This also shows that you can store the reusable template library code with the template definitions as a DrWimpC application with app name of the path variable that will be used by other applications that load the template definitions, ensuring uniqueness of the name, since the application name must be unique. Also you can store different language versions of the template definitions in the application's resources directory.
Visit web-site at: http://pdm.drobe.co.uk
[Top]