Since the template functions are named in a predefined way and have predetermined parameters DrWimpC App Builder supervises the addition
of template functions to source files using a friendly GUI interface. As already noted the C source files are stored in a sub directory
of the application -
!<appname>.FormSrce.<TemplateFilename>.c.<Filename>
The filename is the same as the
template name.
(E.g. The barobject C source code is stored in !bar.FormSrce.bartmpl.c.barw).
To open the template function
selection menus first select an application from the project window application list. Then, select a template file and template
to work on by using the Template Files and Templates sub menus accessed from the Project windows Project Menu opened from the Project
button.
(2014-09-14)
Follow the template Files sub menu arrow to open a list of template files for the selected application. Select the template file
to work on (which will become ticked). The templates menu item will become selectable once a template file is selected. Follow the
templates sub menu arrow to open a list of templates defined in the template file.
Select the template for which you want to add/edit template functions.. It will become ticked and the template will be opened
as for the barw example here.
An example for the barw barobject is shown below. The illustration shows the Handler Function menus for a <Select> click on
the group icon for the barobject and the initialisation function selected. As it already exists it is ticked.
Follow the sub menu arrow for the category you want to work on. This will open a submenu listing the types of template function available
for the category. If a function already exists its menu entry will be ticked.
Selecting a function's entry will cause an
external edit window to open with the edit cursor positioned at the start of the function body. If it is a new function definition
a skeleton function will be appended to the file contents and the edit window opened at end of file with the edit cursor positioned
at the start of the skeleton function.
You can put in the functionality you require and save the file back to your application.
If
you add your own functions to the file then you should either define them before they are used or create and include a header file
for the function prototypes to avoid compiler missing function errors.
In addition to the skeleton function when a new function
is added a default set of header file include statements are added to a generated header file for the function. The header
file is named after the template with a capital 'I' appended to it and stored in the h directory for the template file. You can
add (or remove) include statements to (from) this file.
The code extract for the barw.barobject function is shown below. The edit cursor is initially placed below the opening curly
bracket for the function body. The parameter list is generated automatically when the function is added.
Points to note are
- The wpwd parameter is a pointer to the DrWimpC library global data structure. The intention of this is to provide access to data similar to the BASIC DrWimp library which defines a set of global data values that are accessible by your application.
- objectid is an internal unique identifier for the object used by the DrWimpC library and certain user functions.
- whan andicon are the window handle of the window containing the object and the icon number of the group icon for the object.
- occno is the object's index - from the icon name index ([1][, [2], etc).
- userwincode is a number defined by you to help identify the type of a window - useful during program setup and initialisation.
-
bar_bartmpl_barw_barobject_d *bd is a locally defined pointer for the structure type described in Template Functions Part 1 that links the data you want to pass to your template functions and is used by DrWimpC App Builder when defining the pointer array of data pointers for the window.
-
Once successfully allocated any initialisation can be done and the pointer returned to DrWimpC library for storing and passing to your template functions.
void *bartmpl_barw_barobject_ini(drw_wimp_data *wpwd,
int objectid,
wimp_w whan,
wimp_i icon,
int occno,
int userwincode)
int objectid,
wimp_w whan,
wimp_i icon,
int occno,
int userwincode)
{
bar_bartmpl_barw_barobject_d *bd;
bd = (bar_bartmpl_barw_barobject_d *)
drw_mem_alloc((int) sizeof(bar_bartmpl_barw_barobject_d),
(drw_mem_flags) 0,
(drwGP_ptr) 0,
NULL);
drw_mem_alloc((int) sizeof(bar_bartmpl_barw_barobject_d),
(drw_mem_flags) 0,
(drwGP_ptr) 0,
NULL);
if (bd)
{
bar_init_app_data(bd);
bd->objectid = objectid;
bd->whan = whan;
bd->objicon = icon;
{
bar_init_app_data(bd);
bd->objectid = objectid;
bd->whan = whan;
bd->objicon = icon;
bd->nudgeupicon = drw_get_iconno(whan,
"bar:bartmpl/barw.nudgeup",
objectid,
(wimp_i) -1);
"bar:bartmpl/barw.nudgeup",
objectid,
(wimp_i) -1);
bd->nudgedownicon = drw_get_iconno(whan,
"bar:bartmpl/barw.nudgedown",
objectid,
(wimp_i) -1);
"bar:bartmpl/barw.nudgedown",
objectid,
(wimp_i) -1);
bd->baricon = drw_get_iconno(whan,
"bar:bartmpl/barw.baricon",
objectid,
(wimp_i) -1);
"bar:bartmpl/barw.baricon",
objectid,
(wimp_i) -1);
bar_enable_nudge_icons(bd, 0);
bd->MANUAL = FALSE;
drw_wimp_start_null_events(objectid,
whan, icon);
}
}
return (void *) bd;
}
Other noteworthy points -
- The function drw_get_iconno allows you to get the icon number of a named icon allocated to the icon when a window is created at runtime.
- drw_wimp_start_null_events is called to cause null events to be processed by DrWimpC library. A null event template function is defined for the barobject to handle the bar icon redrawing.. It will be called when DrWimpC library receives a null event. The data pointer returned by the initialisation function will be passed to the null event template function in the userdata parameter,. All template functions have a userdata parameter used to pass the data pointer.
When a template function is selected from the template function list menu, in addition to an external edit window, DrWimpC
App Builder opens its own function list window containing a list of functions already present in the file, for example the barw
function list window is shown below This window may initially open below the main Projects window. You can select a function name
to move the edit cursor to the start of the function in the edit widow, or enter a line number in the Goto line field and press enter
to move the edit to that line in the file. Selecting the Show Template will cause the template you are working with to be opened and/or
moved to the front of the stack (useful with alot of open windows).
DrWimpC App Builder performs a check that brackets
both round and curly are matched in the file being edited. If they are not an error window is opened describing the
details of the mismatch, and you will see the warning icon unshaded in the Goto Function Selector window.
Selecting <MENU>
when pointing to a function name will open a single item menu allowing you to save the function list as a header file. This is more
useful for your own source files.
Each application has a template file called <appname>ibar containing a template called Ibar. This allows template functions
to be defined for things like <SELECT> and <ADJUST> mouse clicks over your application's iconbar icon. See
also the Defining Shortcuts section that also uses the <appname>ibar / Ibar template as a Hot Key window for your application's
shortcut keys.