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 -

 

 

 

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.

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.

 

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.

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.

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.

 

 

 

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.