drwimpc001011.png drwimpc001012.png
The DrWimp C Application Builder
Template Functions.
DrWimpC 1.22
First, the Template of the title refers to the RISC OS mechanism of defining windows and storing the definitions in a template file that can be loaded by an application and the window definitions in the file used to automate the creation of instances of a window.
Usually icons in a window are referenced by their  icon number - the index of the icon's definition and data in the array of icons attached to a window.. This means that if a template definition is changed the icon numbers of the existing icons could also change as icons are added, renumbered or removed, potentially meaning changes to the source code to test for the changed icon numbers when handling wimp events for those icons.
DrWimpC App Builder allows a greater flexibility by using icon names specified by the  'N' validation code of the icon's validation string. To ensure uniqueness the full name involves the application name, template file name and window definition name to precede the icon name itself. The 'N' validation code can conveniently be placed at the end of the validation string with the following syntax -
* The initial semi colon must be present.
If the icon is only to be referred to in the application that uses it then any or all of the appname, Template Filename and Template name can be omitted.
In connection with the names DrWimpC App Builder allows functions to be associated with icons that handle wimp events when called. These functions are registered by the DrWimpC library when an application is started and called automatically when event for the icons occur.
The function names are formed from the application name, template file name, template name and icon name with a three letter suffix representing the type of event. Each element of the function name is separated by an underline character. In this way events that occur for windows can  be catered for by using no icon name in the function name.
By using the icon name and the automatically called functions, the reliance on icon numbers is overcome, and so is the need to edit source code when an icon number changes.
Use in Objects
Specifying Objects in a Template
!DrWimpC 1.22
Source Code Requirements
!drwdef Part 1
!drwdef Part 2
!drwdef Part 3
Template Functions Part 2
External Dependency Links for !DrWimpC.
Compiling Template Functions.
When you add template functions to an application they must be compiled and linked to the application. They must also be registered with the DrWimpC library before they can be called automatically. DrWimpC App Builder generates code to do the registration and call any library initialisation functions for the events to be handled. To do this you must select the 'Build' option from the Project window's 'Compile' menu. This causes DrWimpC App Builder to regenerate the registration source code to include the new template functions and compile that and the template functions into libraries.
The registration source code is stored in the application in the FormReg directory in sub-directories named according to the template file name that has the window/icon defined in it. (Currently 'rg' is appended to the template file name to form the sub-directory name).  
The template functions themselves are stored in the application in a directory named FormSrce in sub directories named after the template file containing the window/icon definition.
In each case a C source code directory is used to store C files named after the window definitions.
When an application is compiled these C files are also compiled and built into libraries stored inside the FormReg and  FormSrce sub directories. These are then linked into the application. For shared library versions the registration functions in the FormReg directory are linked into the shared library for the template code in the FormSrce directory. This avoids excessive shared libraries at run time.
FuncProc v500
This web site without the zip files.
Back to TOP
ReusingTemplate Functions.
Compiling the template functions and their registration code into libraries means they can easily be reused in your application, or other applications. The use of unique names and the linking of the names to functions means that all that is required to reuse them is to include the icon definitions in the window where you require them. This can be easily achieved with a template editor such as Wined. Then just build the application to activate the template functions.
DrWimpC App Builder automatically generates make files and C source code to include the template functions for the icon definitions and the DrWimpC library links them to the window containing them when a window is created from its template definition when your application is started. Note that the icon full name including all name elements must be used to achieve this.
Back to TOP
Objects Using Template Functions.
DrWimpC App Builder provides a mechanism to group together icons so that 'objects' using template functions can be created and reused. An example of this is the !bar application included in the DrWimpC Object Repository' with source code. The example, originally from the BASIC DrWimp library has a window with a moving bar that can be manually controlled using up/down buttons when manual mode is selected from the window's menu. In DrWimpC App Builder the moving bar, up/down buttons and menu are combined into an 'Object' that can be reused in other applications by the simple template edit and one 'Build' of the application code as described above. If you require several objects of the same type in a window all that is required is to edit the window definition and rerun the application to see the new window with all the defined objects in action. No further recompile is necessary since the library code for the template functions is already linked into the application. One additional step is required to identify each element of the array is to append an index to the name in square brackets - e.g. [3] during the template edit to place the objects in a window..In the absence of the index DrWimpC library will allocate the array index to each object of a given type based on its location in the window definition - starting at 1 from the top left of the window definition. It is usual to define a single object with index [1] in a template and then use it as a building block in other templates. Once copied into another template you can edit and move icons in the object as long as they still remain in the bounds of the group icon, which itself can be resized to accommodate the moved icons. For an example of this see the !bar2 example where the barobject of !bar is reused with 4 barobjects. Note that the menus associated with the barobject are also associated with the barobjects in !bar2. Even new objects based on the !bar barobject can be created as two are in !bar2.
Back to TOP
Specifying Objects in a Template.
DrWimpC App Builder and DrWimpC library identify an object and its icons in a template definition by using a base group icon that encompasses the extent of the object in a window. The group icon can   optionally be hidden when a window is created. WinEd is particularly useful for this. It has a group icon in its Picker window that can be used for this purpose. First drag a group icon from the Picker window placing it in your window definition at the required location. Give it an appropriate icon name using the 'N' validation code, optionally give it an index of [1]. Then, add subsequent icons from the Picker window such as up/down buttons, etc placing them within the boundary of the group icon and giving them a name as before. You can examine the !bar barw template definition in the bartmpl template file to see an example of this. The full application name, template file name and window name must be supplied for the icon, then its own specific name. All icons within the boundary of the underlying group icon are identified as belonging to the same object, and when this group of icons is included in another template definition in the same, or another, application DrWimpC App Builder will link in the associated library of template functions into the application, and at run time DrWimpC library will register the functions with any windows created from the template definition.
Normally the underlying group icon will not be shown in a window. To retain it so that it will be displayed at runtime just append an asterisk to the group icon's name.
Source Code Requirements for Objects.
This might look and sound complicated but there's just alot of words to describe the straightforward a mechanism. I use the !bar example supplied with !DrWimpC to illustrate the idea. I recommend you open the !bar application and examine the files mentioned here.
The!bar application is in the DrWimpC Repository which is the recommended location to store applications which have reusable Template Objects since as part of DrWimpC App Builder resources and defaults application, !DRWDEF it will be seen by the filer before the templates and objects are used.
You can open the DrWimpC Object Repository by selecting the Open Repository item of the Projects window Objects button. Then you can either open !bar from the App button's Open item or by the usual <shift> + double clicking the !bar filer window icon.
Back to TOP
Each object type should have its own structure that holds data about its state. For example the barobject object in !bar keeps track of the bar's size, its step size, etc.
Briefly, the object initialisation function passes in its parameters the window and icon to which the object data applies, a user defined integer code that can be used to identify the window type in your application (useful during application  initialisation), a unique internal objectid that can be used to retrieve a pointer to the object's structure, and is used by the DrWimpC library for various things, and a pointer to the DrWimpC library global data structure. The object's index in the window is also available as a parameter. The initialisation function is called for each object defined in a window. In this way arrays of objects are supported at source level and you can supply a data structure for each object in the array. The array index starts at 1.
The important bit is to return a pointer to the structure (as a void *) that the DrWimpC library can store and pass to your template functions. In this way you can communicate any data needed by your template functions.
Initialisation functions are defined for icons. DrWimpC App Builder uses the special case of no icon to define a generated initialisation function for each window that contains template objects.  It then generates a structure consisting of an array of pointers where it stores the pointers you return from the object's initialisation function.  To do this it defines a data structure with a name derived from your application's name, the template file name containing the window and the name of the window's template definition.
In addition a constant is #defined for the number of objects in the window and a function (and its prototype)  that you can use to retrieve a pointer to the structure..
E.g. for the !bar barobject, the template file name is bartmpl, and the window name barw giving a structure name and definition of
 typedef struct bar_bartmpl_barw_data  bar_bartmpl_barw_data;

#include "bartmpl/barwh.h"
#define bar_barw_bar_barw_num_barobject 1
struct bar_bartmpl_barw_data {
bar_bartmpl_barw_barobject_d *barobject[bar_barw_bar_barw_num_barobject];
extern bar_bartmpl_barw_data *
       bar_bartmpl_barw_get_wdata(wimp_w whan);
These definitions are stored in a generated header file that is stored in a sub directory of your
application. The sub directory name is just the application name. Inside it an h directory is created and the file stored in it. The header file's name is just the application name with an underline happened to it. So, for the !bar application it is bar_.
You can include it in your application by the include statement #include "bar/bar_.h".
This gives your application  access to the array of pointers to the data for the objects defined in the window.
Back to TOP
This process is done for each object type in the window resulting in an array of pointers for each object type. For this to succeed, DrWimpC App Builder needs to know the name of the structure you allocate in your object's initialisation function to hold the objects state data and whose pointer is returned by the initialisation function.. This also allows DrWimpC App Builder  to generate code using the structure name instead of using opaque void * pointers. Because of this, a naming convention is is used by DrWimpC App Builder.
The structure must be named using the application name, template file name, window name and icon name
of the icon for which you define the initialisation function with a '_d' appended to it. As shown above, for the !bar barobject object the name is bar_bartmpl_barw_barobject_d as shown above. You must define this structure for the object in a header file stored in the FormSrce h directory for the template file, named using the window name with h appended to it. In this way DrWimpC App Builder both knows the name of the structure and the header file where it is defined and can include it where it needs it - which happens to be in the C sources generated to register your template functions with the DrWimpC library at application start up. For example,  in !bar, the barobject is defined in the barw window - whose template definition is stored in the bartmpl template file. So, the structure definition for the barobject should be stored in the location
For compilation, DrWimpC App Builder generates a SetVars file that is run when !Boot or !Run is executed. A system path variable to point to the FormSrce directory named after the template file is defined. So, for the barobject, and any other template functions defined for the bartmpl templates, the variable bartmpl can be used to locate the C header files by the include statement, for example,   #include "bartmpl/barwh.h"
Back to TOP
Summary Of Steps To Create and Use Objects.
  • Group icons of an object together in the bounds of a group or other icon covering the extent of the object.
  • Name the icons <appname>:<TemplateFilename>/<Templatename>.<iconname>[index] index is only required for the group icon
  • Add an initialisation function for the group icon that returns a pointer to a data structure for the object.
  • Define a data structure in a header file stored in !<Appname>.FormSrce.<TemplateFileName>.h with name <windowname>h.
  • Structure  name has the form, appname_TemplateFilename_Templatename_iconname_d where iconname is the name of the surrounding group icon.
  • .Add template functions for the other icons as necessary.
  • To compile into a  library select the 'Build' option for first compile, Otherwise 'Make'.
  • Reuse by placing object icons into other application's templates and Build/Compile the application 
Next: Template Functions Part 2.
Previous: Defined Menus.