DrWimpC Program Initialisation.

1. StartUp.

The program entry point is the main() function which is defined in the drwapp.c file as extern int main(int argc, char *argv[]) { drw_app(argc,                 argv,                 &drw_u_lib_init,                 &drw_u_templates_register,                 &drw_u_set_app_name,                 &drw_u_setup_uwdata,                 NULL); return 0; }

The drw_app() function passes the program's argument string (and number of parameters) to the DrWimpC library initialisation code which stores it in the user wimp data structure so your program can access it at a later time. The pointers to the user function's drw_u_lib_init(), drw_u_templates_register(), drw_u_set_app_name(), and drw_u_setup_uwdata() might look a bit strange. The reason for passing pointers to these functions is twofold. First, the DrWimpC mechanism for calling user functions is through an array of pointers to the user functions. The array is set up during the DrWimpC library initialisation at application start up. This allows the use of user functions to be optional rather than having to link with default versions for each wimp lib action as in the BASIC drwimp library. Secondly, the user functions are defined for each application and are not compiled as relocatable code so the GCC 4 shared library version should not be directly linked to them. The four functions listed are called prior to the array of pointers to the user functions is created because information from the initialisation they do is used to determine the size of the array and how it is allocated. Passing them to the library initialisation code as pointers to functions gets round the catch 22 that automatically calling them would need the array of function pointers to be set up first, but they need to be called in order to create the array of function pointers.

drw_u_set_app_name() is a generated function used to ensure that the DrWimpC library initialisation procedures know the leaf name of the application (the part after the '!').

drw_u_lib_init() calls library initialisation functions and functions to set elements of the array of user functions for the wimp lib actions used by an application.

drw_u_templates_register() calls the template function registration functions, creates defined menus and loads windows for automatically loded templates and calls librry initialisation functions for those parts of the DrWimpC library required for the template functions to operate. Handles to the created defined menus and automatically loaded windows are stored in externally defined data strudtures so that they are available to your application. (See the !bar, !bar2 and !drwopen drw_u_template_register() functions for examples of this.

drw_u_setup_uwdata() is also defined in drwapp.c and used to allow each application to set and ajdust the various variables in the user wimp data structure before they are used by the DrWimpC library initialisation code. Some of these values can affect the part of the initilisation that is done before the array of pointers to user functions is created and filled so it too is passed as a pointer to function value in the call to drw_app(). The utility !drwopen avalable to download from the program area of the DrWimpC App Builder web site contains a simple example of setting the messages list of the user wimp data structure. The message list is added to the list of messages that an application wants to deal with and receive from the wimp. Now seems an appropriate time to describe the user wimp data structure.

2. The User Wimp Data Structure.

struct drw_uw_data {

wimp_w barwin;

Initialised to (wimp_w) -1. When an application has a window that is opened when its iconbar icon is selected, and the window's template is marked as the iconbar window,then this field is used to store its window handle. To set the icon window flag for the template open the DrWimpC App Builder Project window, select the application and the template file containing th icon bar window's template from the template files sub menu, then open the list of templates sub menu and use the 'Templates' sub menu for the icon bar window template to set the 'Icon Bar Window' flag for the template. E.g. -

Selecting the drwopentmpl file entry enables the 'Templates' menu item and you can follow the sub menus to the 'Template' sub menu for the icon bar window 's remplate - in this case the 'main' template. !drwopen does not need an icon bar window so the flag is unset.

When the Icon Bar Window flag is set a sub menu is enabled allowing an option of which user action will open the window.

Selecting 'Open At App Start' will cause the window to be automatically opened when the application is loaded.

Selecting 'Open On Select'/ 'Adjust' will cause the window to be opened when the applicationis licon bar icon is selected using the 'Select' or 'Adjust' mouse buttons..

The Open Window At menu item leads to the 'open At' sub menu to allow some control over where the window is opened with the 'Open At Box' dialogue providing OS unit level specifiers.

The Open At' Sub Menu.

The Open At Box Dialogue.

The Icon Bar Window name and its settings are stored in a file called 'MainWindow' inside the WinData application sub directory. E.g. the !drwopen main window is drwopentmpl/main+0,0 (even thogh it has been deselected - the default on application creation is to select the 'main' window of the default standard templates file copied from !DRWDEF.Resources.UK).

wimp_w barwinstack;

Initialised to (wimp_w) -1 this field can be set by an application to open the Icon Bar Window in a particular position in the main window stack. Well that was the intention. I'm not sure its actually much use.

wimp_w info; wimp_w savebox;

Similar to the Icon Bar Window, you can select one template to be used as the Info Box dialogue that is attached to the 'Info' item of the application's icon bar menu, and a template to be used as the standard 'Save Box' dialogue. These are specified by selecting the 'Info Box' and 'Save Box' menu items of the 'Template' menu - shown above. These fields are initialised to (wimp_w) -1. The Info and Save Box Window names and its settings are stored in files called 'InfoBox' and 'SaveBox' respectively inside the WinData application sub directory.

wimp_i baric;

When an application has an icon bar icon - i.e. the 'Has Icon' flag in the 'Icon Bar' section of the application Options is set - then the DrWimpC library will automatically call drw_wimp_iconbar() to create the icon bar icon using information in the Options window 'Icon Bar' section for the text that appears under the icon - if any is specified. Note that this is used a s default text. A language specific text can be specified using the optional token '_Ibartext' in the application's 'Messages' file which can be placed inside named territory directories in the application 'Resources' directory. E.g !drwopen has _Ibartext:Open in its Messages' file. It is set to (wimp_i) -1 if not present).

wimp_menu *barmenu;

In DrWimpC App Builder menus can be defined and stored with other program resources in named territory sub directories of the application 'Resources' directory. If the DrWimpC library finds defined menu named 'Ibarmenu' it used this as the menu to be opened when the middle button (or equivalent keyboard menu button is used) is selected when pointing at the applicaiton's icon bar icon. This menu will be automatically created and its handle placed in the barmenu field. (Otherwise set to NULL).

wimp_menu *mainmenu;

This field is no longer used. It has been superceded by the facility to attach a defined menu to a template using the 'IconClick Action' dialogue which is described in the 'Linking Templates and Menus' page of the DrWimpC App Builder web site..

size_t memforwimpblock; char appresdir[drw_uw_appres_dirname_size]; size_t maxobjsize;

These three fields are are set from their corresponding fields in the Application section of the Options dialogue. These values along with other application default values are stored in the dcdefaults file inside the 'Defaults' application sub directory. They all have minimum values of 1K, ;Resources' and 1024 bytes respectively. The memforwimpblock option is the largest size that the application's wimp block needs to be to process all communication with the wimp. The appresdir is fixed to the default value of 'Resources'. (Initially I thought this could be made definable for each application but it wasn't a sensible approach). The maxobjsize is the minimum size that the DrWimpC library's internal buffers need to be to safely store names such as long directory and file names used by an application. The DrWimpC library can adjust the size of these buffers when using them for internal operations but as they are stored in the ,malloc heap it is preferrable to know their maximum to avoid fragmentation of the malloc heap - and buffer overrun.

char appresdirprefix[drw_uw_appres_pfx_name_size];

The resources sub directory name prefix for territories. If you store territory specifc resources such as template files in your resources directory, you can use sub directories named with the RISC OS territory name (UK, Germany, etc), or use the territory number, prefixed by this string (e.g. if the prefix is terr_, the UK territory sub directory would be named terr_1).

int savedesktopflag; wimp_version_no version_in; char *appsyntax; char ibartext[drw_wincode_name_size]; int ibarmaxlen;

These fields are also stored in the dcdefaults file derived from their corresponding application Options. The savedesktop facility is deprecated in RISC OS now so the flag is ignored by DrWimpC library. The wimp version number is passed to the swi Wimp_Initialise. Default value = 300. Appsyntax field was never impemented in DrWimpC App Builder. It is also ignored by the DrWimpC library. The ibartext is as described above for the Icon Bar icon. It is limited internally by DrWimpC library to 16 characters, incluudng a zero string terminator.