DrWimpC library

The DrWimpC C Library.

This is a brief introduction to the library. At the moment it serves only to get you started writing C wimp applications using the library. More comprehensive details and tutorials will follow..

The BASIC DrWimp Library is a single file that is included in a BASIC !RunImage at run time using the LIBRARY command. The C version by contrast, is split into a number of separate files where functions that carry out a particular wimp library action are grouped together. The standard user files are similarly organised. This is so that the link tool used to produce the !RunImage file only includes in the final !RunImage file those object files that have functions and actions used by your application. In this way the code size is reduced compared to requiring the entire library to be present in your application.

So (at present), to find out which function to call for a particular facility you should consult the header files. These are stored in the DRW directory in the subdirectory DRW in the h directory (Including the standard User File prototypes). As a guide, note that every function in the BASIC library has an equivalent function iin the DrWimpC library. I recommend the BASIC libraries StrongHelp FuncProc manual as a starting point to find the name of the function you require. e.g FNwimp_loadwindow has the C equivalent drw_wimp_loadwindow which has its prototype definition in header file drwWcreate. The libraries h directory contains the function prototype definitions of all the functions used in the library. In your program you can safely use those functions which have equivalents (exact or near) to the BASIC functions and procedures.

Important Differences when Programming with the C Library (compared to the BASIC Library).

Function Name Prefixes

All DrWimpC library functions are prefixed by drw_. All DrWimpC standard user functions are prefixed by drw_u_, apart from several new functions defined for use with menus, which are prefixed by drw_user.

New User Functions

There are a number of new user files and functions. Notably, file drwUWcr which has a function that is called immediately prior to the window bwing created. This allows you to alter any window and icon data (say fom a template definiton) according to circumstances.

I have introduced the notion of a user window type. This is an integer with reserved values 1 - 260. User values starting at 261. The idea is that in more complex situations you can identify the window being created by this type value. Its use is optional, 0 = no value supplied.

Similarly for menus I have introduced four user functions in file drwUMmisc. The two most important ones are drw_user_menu_title and drw_user_menu_text which are called immediately prior to the menu title and menu item being created for a menu. This allows last minute laterations, or specification of text, including wheter the Library shuld allocate storage for the text or not - so that you can specify text from an already allocated memory location (e.g. a structure that has been allocated storage - the idea being to reduce duplication and memory requirements. The other two functions in this file apply to new ways of creating menus. The most useful is drw_user_count_menu_items which is used to create menu items from a user specified memory block.

Menu Creation

I mention this now because it is a significant difference to the BASIC library. In the C version menus are dynamic in that they need not have a maximum size. They can be resized beyond their initial size value supplied in the menu_create function. However, this adds the slight complexity that they can move in memory. So, you must always assign the return menu pointer value from a menu function to the menu pointer in your application. Otherwise, the menu definition could be moved in memory, but the pointer you are using in your application would still be pointing to the old location and referring to it would have odd effects, or cause crashes.

As for windows, I have introduced a menu type, also an integer, 0 = no vlaue aupplied. This allows your code too easily identify which menu is being create, or amended in functions like drw_user_menu_text().

To see the full range of menu creation/alteration functions refer to the header file drwWmcr.

The Main DrWimpC Header File - drwwh.

This file contains standard C and OSlib library includes required in the C library and user file sources, as well as the definition of the Standard DrWimpC Library Wimp Data Structure., and so occurs in most or all C soource files as a matter of convenience and necessity

The Standard DrWimpC Library Wimp Data Structure.

In BASIC variables that are declared outside functions, or are not declared as LOCAL, have global scope in the program. In a C program there may be more than a single source file that is compiled and linked together to form the final executable program. As well as having the equivalent of local scope a variable is declared inside a function definition, a variable declaration can be made outside the functions of a source file, when it has global scope for all the functions in the source file. Such a variable can be referred to in other source files by prefixing the declaration with the extern label (it has external linkage).

So, I have grouped together all variables declared in the BASIC DrWimp library with global scope into a single structure, the Standard Wimp Data structure. The DrWimpC initialisation code allocates storage for this structure at application start up, and the pointer to it is declared with the extern label to give it external linkage, and there is a header file drwWxdata which contains its external declaration - extern drw_wimp_data *pwd; This header file is icluded by all the standard user source files. This means you can access the global variables as in the BASIC DrWimp library by pwd-><variable name>.

Just as Ray Favre has noted for the BASIC DrWimp library, it is not necessarily sensible to change the values of the global variables, however, there are some exceptions, and some extra values in the DrWimpC Standard DrWimpC Library Wimp Data Structure. Notably, the info box fields (author, purpose and version) and the appname - the short application description that appears in the task manager display can be changed before they are used to set the info box fields, or the appname passed to the wimp_initialise() function. There are four user functions in the standard user file source - drwUwinit to do this - drw_u_get_appname, drw_u_get_apppurpose, drw_u_get_appauthor and drw_u_get_appversion. If there are values in the application messages file for these fields, then this value passed to the functions in the buffer parameter.

Standard Buffers

.
The DrWimpC library also uses internally allocated buffers to hold, temporarily, pathname values and string return values (whereas in the BASIC DrWimp Library a function's return string value is passed back into an existing string, or a new string variable is created as a result of the return form the function).

There are three main buffers allocated on application start up, with size equal to the maximum object size specified in the application details dialogue. The wimp block used by DrwimpC to interact with the window manager is also available to your program.

The buffers are

stdwkbuffer
workvar and
wmessageout

They are declared as char * types, and can be accessed using the global data pointer pwd, e.g. pwd->workvar. This may be convenient if you intend to immediately use a string result returned from a function in one of these buffers. Be aware that the DrwimpC library makes extensive use of these three buffers, particularly in pathname operations, and retrieving messages from message files, so you must take care that your use of a buffer does not conflict, or interfere with the DrWimpC library usage of the buffers.

wimpb This is the wimp block used by the DrWimpC library to receive events and messages from thw wimp. It is a byte * type. You can refernce it from your program using the global data pointer to the standard DrwimpC wimp data structure, pwd - i.e. pwd->wimpb.

Further, the global flag values such as NULLVAL% are integer types in the BASIC DrWimp library, but the C data structure combines these into a singke flag word using a single bit for each flag and a defined constant to get and set its value in the flag word. For example, NULLVAL% has the constant DRW_NULLVAL. So to receive Null events in your application via the drw_u_null() function set the flag. (Since this amnual was written the handling of null events by DrWimpC library has been enhanced beyond setting this single flag. Instead a set of functions is used to sar or stop receiving null events. This is so that an applicaton can receive null events for more than one purpose simultaneously without needing to keep track of how many uses it is making of null events at any time. DrWimpC library maintains a count of the number of times you start and stop receivong null events. When this count is non zero it sets the wimp mask for Wimp_Poll to receive null events, and unsets the mask in order to stop receiving nuul events when the count returns to zero. So, you shouldstart and stop null events once for each purpose your application uses them. The functions to do this are described in the StrongHelp DrWimpCAPI manual. You can open the manual fromthe !DrWimpC iconbar menu. The DrWimpCAPI Stronghelp manual is stored in !DrWimpC.Resources.UK. You can copy it to !Manuals so it appears in the StrongHelp list of manuals.

pwd->flags |= DRW_NULLVAL; No longer needed. The DrWimpC library sets this flag when you tell it to start receiving null events.

and to stop receiving them unset the flag with

pwd->flags = pwd->flags & ~DRW_NULLVAL; No longer needed. The DrWimpC library sets this flag when you tell it to stop receiving null events.

The other flags that have a BASIC version are

DRW_quit: Equivalent to quit%, set this to cause the application to closedown.
DRW_wfinished: Equivalent to wFinished%. Set this to exit the wimp_poll loop.
DRW_wprinting: Equivalent to wpriting%. Use to indicate direct printing.
DRW_wBANNER: Equivalent to wBANNER%. Use when you want to display a window for a period of time. Null events are enabled for this time period.
DRW_wBARTEXT.: Equivalent of wBARTEXT. This is superseded by a standard user wimp data option, so has no effect in DrWimpC. See the application details dialogue for details of the option.
DRW_NULLVAL: Equivalent to NULLVAL%. Use to enable and receve Null events in your application.
DRW_UNUSED_: Equivalent to UNUSED%. Set to receive wimp messages that are not automatically handled by th library.
DRW_OBJDONE: Equivalent to OBJDONE%, it is obselete. No longer supported.
DRW_wICONISE.: Equivalent wICONISE%.

The other flags in this word are for internal use, execpt for the three memalloc flags: DRW_alloc_mem_for_str, DRW_alloc_mem_for_valn_str, DRW_alloc_mem_for_sprite. These are important when you manually create icons. If you want the library functions to allocate storage for the icon text, validation string or, then set the appropriate flag. There is a function,drw_wimp_set_imem_flags, which takes three parameters, a TRUE/FALSE value for each flag, to enable you to set or unset the flags. The functon's prototype is

void drw_wimp_set_imem_flags(int allocstr, int allocvalnstr, int allocsprite);

The example program !Create which illustrates the manual creation of windows and icons uses this function.

Application Messages

DrWimpC loads the application message file automatically at application start up. It stores its handle in a structure called appmsgs in The Standard Wimp Data Structure. You may refer to the message file handle by pwd->appmsgs.msghandle when looking up or counting messages. If no message file was found, pwd->appmsgs.msghandle is NULL.

The BASIC DrWimp library, from version 4.40, has pulled together the message lookup functions into one single function with up to 2 parameters. The C version has kept in step with this and done the same but also retains the older group of functions, with a function for each of 0, 1, 2, 3 or 4 parameters. The functions are drw_wimp_messlook<n> where n is in the range 0 to 4, and is the number of parameters in the message to be looked up (and parameter values supplied to the function). In fact, these message lookup functions all call one underlying message lookup function to do the messagetrans look up.

The Standard User Wimp Data.

Whilst you can set up your bar window and menu data yourself using the C library functions, the library provides a means, along with the dcdefaults file which stores options from the application details dialogue, of automating the creation of a bar icon, a bar window that can be opened at start up or by clicking <SELECT> on the application's bar icon, and a bar icon menu, opened when you click <MENU> on the bar icon. To allow the application access to the created window and mneu handles, amongst other things, there is a structure - drw_uw_data - which is defined in the header file drwUwdata. It contains the fields barwin and barmenu which are used for the handles of the created window and menu. The structure also contains handles for the info and a savebox dialogue which can also be automatically defined. If you are creating these items manually you can use these fields to store their handles for later use im your application. Threre is also a mainmenu pointer file which you can use when you create a menu for the application's main window, if it is not the same as the bar window.

The options stored in the dcdefaults file are read into the drw_uw_data at applicationb start up, and a user function is provided, drw_u_setup_uwdata(). so that your application can change these on the fly. It is called before the C library application initialisation code uses the values. The only value you should not change is the appdirname, which is set to the application's name as entered in the New Application Dialogue.. There is a flag word that stores indicators such as whether the application's icon appears on the right or left side of the icon bar. These flags can also be altered by the user application in drw_u_setup_uwdata().

The structure is available to your application by means of the Standard DrWimpC Wimp Data Structure which has a pointer to it, named uwd, so your program can refer to it and its values. Perhaps the most useful value in the drw_uw_data structure is the void *appdata pointer which is there so that your apppication can pass a handle - an application specific pointer to data that is used throughout your applicaton. This is useful in passing data between source files and avoids lots of external definitions. E.g. Declare a data structure (myappdata) in the drwUwinit C source file containing window and menu handle fields and other data definitions that are used in more than one C source file in your application, so that you can initialise the fields by loading windows, creating menus, loading fonts, etc, and then set the appdata pointer in the standard user wimp data structure to the address of the myappdata structure - pwd->uwd->appdata = (void *) &myappdata. Then functions in other C source files

Values in the User Wimp Data Structure.

Since this manual was written GCC gas progressed to version 4 making the drlink flags. etc out of date and ignored by DrWimpC App Builder. New flags have been added for ELF fornat and shred libraries.

wimp_w barwin;: The handle of the window that is opened as a result of clicking <SELECT> on the application's icon bar icon, or at application start up if the open at start up flag is set, and you have provided a window definition name. You can, of course, use this field in your application if you manually create this window.
wimp_w barwinstack;: The position in the window stack of the barwin window the first time it is opened.
wimp_w info;: The handle of the application's info box. This is created (and set up) automatically if the create info box flag (and fillin flag) are set. You can also manually create and set it up in your own code.
wimp_w savebox;: The handle of the application's save box. This is created (and set up) automatically if the create save box flag is set. You can also manually create and set it up in your own code.
wimp_menu *barmenu;: The menu handle of the menu that is opened when you click the MENU button with the mouse pointer over your application's icon bar icon. This menu is created automatically if you set the has menu flag. If you specify a message token name, then the menu is built from menu items found in the specified message file (or default application messages file Messages). The message tokens should be suffixed by an index number starting with 1. (e.g. BMENU1, BMENU2, ...). If you don't specify a message token name and file, then if you set the Std menu flag a standard menu of three items (Info, Help and Quit) is used, if this flag is also not set then no menu is created automatically.
wimp_menu *mainmenu;: An additional menu handle for your application's convenience. It may be that the window opened at start up, or by clicking on the icon bar icon is not your main application window. This field is supplied so that you can create a menu for the alternative window, and store the menu's handle in this structure. Then, it is easy to refer to the handle in funcion in other source files, such as the menu selection handler function drw_u_menuselection in file drwUMsl. (Well, I found it convenient, since the user wimp data structure is always available via the stanard wimp data pointer (Then pwd->uwd->mainmenu is the menu handle.).
size_t memforwimpblock;: The maximum size in bytes you expect a window definition and its icons will require in your application.
char appresdir[12];: The name of the directory to store directories and files needed by your application, including territory specific data. Note the name is limited here to 11 characters plus the c string delimiter.
size_t maxobjsize;: The maximum command line or file system path name length in bytes you expect your application to deal with. Default is 1024 bytes.
char appresdirprefix[12];: 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 maxmessagefiles;: The number of message files used by your application. (Superceded by a linked list implementation that does not limit the number of message files). A structure is allocated storage for each message file used. If you only use the standard messages file (Messages) then you don't need to specify a number here because the standard messages file is handled separately, and is available to you from the standard wimp data structure - See Application Messages.
int savedesktopflag;: Set this flag to enable your application to save data to the Desktop boot file when the desktopsae message is broadcast by the task manager.
wimp_version_no version_in;: The wimp version number passed to the wimp_initialise() function. Default is 300.
char *appsyntax;: Not currently used. It is for a command line argument syntax string to be used with os_read_args().
char ibartext[16];: The text that appears below an application's icon bar icon.
int ibarmaxlen;: The maximum length for the icon bar icon's text.
char *ibarmenutitle;: The title of the icon bar menu. (Superceded by the Defined Menus and Templates Menu flags facilities to identify the iconbar menu). If you specify a message token name for messages that are used to build the menu, then you can include a menu title message text by suffixing a T or t to the message token name. (e.g. BMENUT).
char ibarmenutok[12];: (Superceded by the Defined Menus and Templates Menu flags facilities to identify the iconbar menu). The message token name for the bar menu definition. The message tokens should be indexed from 1. (e.g. BMENU1, BMENU2, etc) so there is one mesage text for each menu item.
char *ibarmfile;: (Superceded by the Defined Menus and Templates Menu flags facilities to identify the iconbar menu). The name of the message file where the bar menu messages reside.
int barmenusize;: (Superceded by the Defined Menus and Templates Menu flags facilities to identify the iconbar menu). The initial number of menu itms in the bar menu.
wimp_colour barmenufgcol;: (Superceded by the Defined Menus and Templates Menu flags facilities to identify the iconbar menu). The style guide should be adhered to. However, as I found the Risc Os desktop a bit bland with those colours, I tried different combinations by setting the menu colour values here. After all, the colours are there to be used. Set this balue for the foreground bar menu item colour.
wimp_colour barmenubgcol;: (Superceded by the Defined Menus and Templates Menu flags facilities to identify the iconbar menu). The backgorund bar menu item colour.
wimp_colour barmenutfgcol;: (Superceded by the Defined Menus and Templates Menu flags facilities to identify the iconbar menu). The forekgorund bar menu title colour.
wimp_colour barmenutbgcol;: (Superceded by the Defined Menus and Templates Menu flags facilities to identify the iconbar menu). The backgorund bar menu title colour.
char mainwinname[wimp_TEMPLATE_NAME_LIMIT + 1];: (Superceded by the Templates Menu flags facilities to specify the main (iconbar) window). The name of a window definition in a template file for the bar window. Note the name length.
char infoboxname[wimp_TEMPLATE_NAME_LIMIT + 1];: (Superceded by the Templates Menu flags facilities to specify the info box window). The name of a window definition in a template file for the info box.
char saveboxname[wimp_TEMPLATE_NAME_LIMIT + 1];: (Superceded by the Templates Menu flags facilities to specify the save box window). The name of a window definition in a template file for the application's save box.
char templatemain[16];: (Superceded by the Templates Menu flags facilities to specify the main (iconbar) window). The leafname of the application template file containing the window definition of the bar window. Default is StdTmpl.
char templateinfo[16];: (Superceded by the Templates Menu flags facilities to specify the info box window). The leafname of the application template file containing the window definition of the application's info box. Default is StdTmpl.
char templatesave[16];: (Superceded by the Templates Menu flags facilities to specify the save box window). The leafname of the application template file containing the window definition of the application's save box. Default is StdTmpl.
drw_visible_window_posn mainwinpos;: (Superceded by the Templates Menu flags facilities to specify the main (iconbar) window). A field giving the choice of screen position to initially open the bar window.
wimp_i info_name;: Because the BASIC DrWimp standard info box uses icon number 0, 1, 2 and 4 for the icon nnumbers of the four felds in the info box, I decided to let them be user specified to avoid much editing of current info boxes. This is the icon number of the info box app name field. Default is 0.
wimp_i info_purpose;: Icon number of the info box app name purpose. Default is 1.
wimp_i info_author;: Icon number of the info box author field. Default is 2.
wimp_i info_version;: Icon number of the info box version field. Default is 4.
wimp_i info_website;: Icon number of the info box web site field, if it has one. Default is -1. this field is new to BASIC DrWimp 4.40, so is also new to DrWimpC.
wimp_i save_fileiconno;: The C library has default icon numbers for the standard save box fields, but I haven't assumed anything about the actual application's save box, which can have any number of icons in it. So, you can specify the icon numbers of the three action buttons here. (The C library uses these internally in the handling of the standard Save dialogues). This is the icon number for the file type icon. Default is 0.
wimp_i save_filenameiconno;: The icon number of the Save box file name icon. Default is 1.
wimp_i save_ok_iconno;: The icon number of the Save box OK button. Default is 2.
drw_uw_flags flags;: The user wimp data flag word. It has many bit flags, and is described separately.
char appdirname[12];: The application's leafname, as entered in the new application dialogue's application name field. Do Not Change This Name, unless you change the name of the application, when you MUST change this name to the new application name by directly editing the dcdefaults file.This is always the last entry in the file.
void *appdata;: This is an application supplied field. You can use it to hold a handle to an application defined structure that can be passed to function's in source files other than the one where the structure is declared. The contents of the user wimp data structure is always available using the pointer in the standard wimp data structure. (The header file drwUxdata has one entry in it - extern drw_wimp_data *pwd; Include this file to gain access too the standard wimp data structure, then the user wimp data structure pointer (pwd->uwd). You can then access your application's data structure from as pwd->uwd->appdata, by declaring a local variable as a pointer to the data structure and casting the appdata pointer to its type. e.g. myappdataptr (my_app_data *) pwd->uwd->appdata.
wimp_message_list *messages;: Application supplied field. A list of wimp messages that your application wants to receive from the wimp. It is passed on to the call to wimp_initialise(). The wimp_message_list type is an OSLib type defined in OSLib header file wimp.h.
int waitforeditor;: This is an internal field reserved for use with !DrWimpC. It is the Editor delay centisecond value specified in the Application Details Dialogue Misc section.
char *datahandle;: Also use with !DrWimpC it names a data pointer to be passed to the automatically called window and icon functions. Default is the string NULL.
void *localconv;: The pointer returned from the call to localeconv in the drw_initialise function called from the main() function.
char *ccflags;: For use with !DrWimpC, stores the user supplied part of the ROOL compiler flags string for the application, it is used in the compiler flags when generating the application's make file.
char *gccflags;: For use with !DrWimpC, stores the user supplied part of the GCC compiler flags string for the application, it is used in the compiler flags when generating the application's make file.
char *ccwarnings;: For use with !DrWimpC, stores the user supplied part of the ROOL compiler warning flags string for the application, it is used in the compiler flags when generating the application's make file.
char *gccwarnings;: For use with !DrWimpC, stores the user supplied part of the GCC compiler warning flags string for the application, it is used in the compiler flags when generating the application's make file.
char *linkflags;: For use with !DrWimpC, stores the user supplied part of the ROOL link warning flags string for the application, it is used in the link flags when generating the application's make file.
char *drlinkflags;: For use with !DrWimpC, stores the user supplied part of the drlink flags string for the application, it is used in the drlink flags when generating the application's make file.
char *libfileflags;: For use with !DrWimpC, stores the user supplied part of the ROOL libfile flags string for the application, it is used in the libfile flags when generating the application's make file.
char *gnulibfileflags;: For use with !DrWimpC, stores the user supplied part of the GNU libfile flags string for the application, it is used in the libfile flags when generating the application's make file.
osspriteop_area *mainwsprites;: Pointer to the sprite area containing the sprites for the bar window. If the window is automatically created, you can specify the name of a spritefile that contains any sprites for the window. (The name is held in the mwsprfile field of this structure). You can also set this to a sprite area loaded manually in user function drw_u_setup_uwdata().
territory_t tno;: Application supplied value. This lets your application set which Risc Os territory to use in the application. It should be set in drw_u_setup_uwdata() before the DrWimpC C library application initialisation code uses the value.
char *mwsprfile;: The name of the sprite file containing any sprites used in the bar window. If the bar window is created automatically, DrwimpC allocates storage for the sprites, loads the sprite file and passes the pointer to the allocated sprite area to wimp_create_window function.
void *mainwdata;: If you have any automatically called window or icon functions in the bar window, you can use this field to pass the address of a data structure to be passed on to the automatically called functions.

User Wimp Data Flags.

The flag word is a set of bit flags that hold the settings of flags from the Application Details Dialogue, along with one or two internally used flags, and an indicator to keep track of whether the bar window is open or not.

Note each value can be set by bitwise ORing the flag word with the value in the list:

pwd->flags |= <flag value>

and unset by bitwise ANDing the flag word with NOT<flag value>

pwd->flags = pwd->flags & ~<flag value>

Here is the list of flag values, and a brief description of each flag.

drw_mainwinopen (drw_uw_flags) 0x1u: The bar window open at start up indicator. When on the bar window is opened at the position indicated by the mainwpos field. Default is off.
drw_setupmainwin (drw_uw_flags) 0x2u: The load bar window automatically flag. When on the DrWimpC library initialisation uses the mainwinname and templatemain values from this structure to load the bar window definition, placing its handle in the barwin field. Default is on.
drw_hasibaricon (drw_uw_flags) 0x4u: When on the DRWimpC library initialisation creates an icon on the icon bar for your application, with the text, if any, from the ibartext field. Default is on.
drw_ibariconlhs (drw_uw_flags) 0x8u: Indicates which side of the icon bar the icon bar icon should appear. Set it for the left hand side. Default is off.
drw_hasbarmenu (drw_uw_flags) 0x10u: Indicates if a bar menu should be created. This flag is used with drw_stdbarmenuitems, ibarmenutok and the ibarmfile fields. The barmenu field points to the created menu. Default is on.
drw_stdbarmenuitems (drw_uw_flags) 0x20u: If the drw_hasbarmenu flag is set, this flag indicates if a standard three item menu of Info, Help, Quit should be created. This flag is only used if you haven't specified a message token and message file in the ibarmenutok and the ibarmfile fields. Default is on.
drw_setupinfobox (drw_uw_flags) 0x40u: The load info box automatically flag. When on the DrWimpC library initialisation uses the infoboxname and templateinfo values from this structure to load the info box definition, placing its handle in the info field. Default is on.
drw_setupinfofields (drw_uw_flags) 0x80u: Indicates that when an info box is automatically loaded, its fields should be filled in from the appname, purpose, autohr and version fields of the standard wimp data structure. Default is on.
drw_stdinfobox (drw_uw_flags) 0x100u: Indicates that the name of the info box template is stdinfo. This is only used if no name is specified. Default is on.
drw_attachinfobox (drw_uw_flags) 0x200u: When an info box is automatically loaded, this flag indicates if it should be attached to the automatically loaded bar menu. Default is on.
drw_setupsavebox (drw_uw_flags) 0x400u: The load save box automatically flag. When on the DrWimpC library initialisation uses the saveboxname and templatesave values from this structure to load the info box definition, placing its handle in the savebox field. Default is off.
drw_stdsavebox (drw_uw_flags) 0x800u: Indicates that the name of the info box template is stdinfo. This is only used if no name is specified. Default is on.
drw_useterrname (drw_uw_flags) 0x1000u: This flag is used by DrWimpC library functions when searching for a resource file such as a template file when loading a window that has different versions for each territory. The flag indicates that the names of territory sub directories are the names of Risc Os territories. The sub directory used is the name of the territory of the territory number field. Default is on.
drw_useterrno (drw_uw_flags) 0x2000u: This flag is used by DrWimpC library functions when searching for a resource file such as a template file when loading a window that has different versions for each territory. The flag indicates that the names of territory sub directories are based o the the Risc Os territory numbers. The sub directory used is the concatenation of the appresdirprefix and the tr#erritory number of the territory of the territory number field. The drw_useterrname setting takes precedence over this flag setting. Default is on.
drw_appnameisreg (drw_uw_flags) 0x4000u: Use this flag to tell the DrWimpC library that it can reliably use the system variables <Application_name$Dir> and the <Application_name$path> variables that application registration guarantees are unique. It is up to your application to set this flag in drw_u_setup_uwdata, e.g. by testing for the presence of the application's $dir and $path system variables. Default is off.
drw_noopenappmsgfile (drw_uw_flags) 0x8000u: If this flag is set then the DrWimpC library initialisation code will not try to open the application's message file. Default is off.
drw_nolibmsgfile (drw_uw_flags) 0x10000u: The BASIC DrWimp library's messages are hard coded, but the DrWimpC library uses a message file called libmsgs whic is stored inside the application when it is crated using the New Application Dialogue, so allowing other language versions of the library's messages to be used. The library also has a hard coded English message list, so if you use the default English libmsgs file, you can set this flag to use the hard coded message list. Default is off.
drw_mainwinisopen (drw_uw_flags) 0x20000u: This flag is *not* used.
drw_uwd_defined (drw_uw_flags) 0x40000u: An internal flag for use by !DrWimpC.
drw_def_compiler_cc (drw_uw_flags) 0x80000u: When set this flag indicates that the Norcroft compiler supplied with the ROOL tools be used when generating make files. The flag is also updated when the Set Default button is SELECTed in the Dev Choices Dialogue. Initial value is off.
drw_def_compiler_gcc (drw_uw_flags) 0x100000u: When set this flag indicates that the free GCC compiler be used when generating make files. The flag is also updated when the Set Default button is SELECTed in the Dev Choices Dialogue. Initial value is off.
drw_def_linker_link (drw_uw_flags) 0x200000u: When set this flag indicates that the ROOL Link linker tool be used when generating make files. The flag is also updated when the Set Default button is SELECTed in the Dev Choices Dialogue. Initial value is off.
drw_def_linker_drlink (drw_uw_flags) 0x400000u: When set this flag indicates that the drlink linker tool supplied with the free GCC compiler suite of programs be used when generating make files. The flag is also updated when the Set Default button is SELECTed in the Dev Choices Dialogue. Initial value is off.
drw_def_libfile_castle (drw_uw_flags) 0x800000u: When set this flag indicates that the libfile tool supplied with the ROOL tools be used when generating make files. The flag is also updated when the Set Default button is SELECTed in the Dev Choices Dialogue. Initial value is off.
drw_def_libfile_gnu (drw_uw_flags) 0x1000000u: When set this flag indicates that the libfile tool supplied with the free GCC compiler suite of programs be used when generating make files. The flag is also updated when the Set Default button is SELECTed in the Dev Choices Dialogue. Initial value is off.
drw_def_make_castle (drw_uw_flags) 0x2000000u: When set this flag indicates that the Make projrct manager and AMU make utility supplied with the ROOL tools be used when generating make files. The flag is also updated when the Set Default button is SELECTed in the Dev Choices Dialogue. Initial value is off.
drw_def_make_gnu (drw_uw_flags) 0x4000000u: When set this flag indicates that the GNU Make utility supplied with the free GCC compiler suite of programs be used when generating make files. The flag is also updated when the Set Default button is SELECTed in the Dev Choices Dialogue. Initial value is off.
drw_merge_appn_sprites (drw_uw_flags) 0x8000000u: For use with !DrWimpC this flag, when set, indicates that sprite files dragged to the Application Details Dialogue should be merged with an existing sprite file.
drw_force_build_appn (drw_uw_flags) 0x10000000u: Internal flag for use with !DrWimpC.

The application Shell

The C entry function main is in the standard user file drwapp. It is copied into an application's C source directory when it is created. The main function consists of a generic call to an initialisation process, then a loop until program exit, followed by a closedown process. The initialisation process retrieves the locale data (a pointer to it) and passes this and the argument list that the application was started with (argv), and number of arguments (argc) to the C library initialisation code by the call to drw_wimp_init(), which will subsequently call the user functions drw_u_setup_uwdata(), and drw_uw_init() (and equivalent template user wimp initialisation functions). These two functions are foryour application to do its initialisation (e.g load windows, fonts, create menus, initialise global values, etc).

The main program loop is a call to a user function drw_uw_poll() in file drwUwinit.c, which just calls the C library poll function drw_wimp_poll() by default. You can, of course edit this to your appllication's requirements.

When your application closes down the main program loop is exited, and the closedown process drw_uw_closedown() (and equivalent template 'wimp closedown' functions) is called. This is another function from drwUwinit.c. In it your program can carry out clear up operations such as closing files, deallocating memory, etc.

The C Library Wimp Poll Functions.

There are four of these, as in the BASIC DrWimp library. howecer, to make the switching on and off of Null events simpler, the C versons take a single parameter of integer type which should take one of the values

DRW_NULLS_CV (0): means use the current setting of the enable null events flag.
DRW_ENABLE_NULLS (1): means set the enable null events flag.
DRW_ENABLE_DISABLE_NULLS (2): means unset the enable null events flag.
DRW_ENABLE_NULLS_TEMP (3): means temporarily set the enable null events flag, until the end of the drw_wimp_poll function. This is normally used in the drw_wimp_pollidle functions. The flag is reset to its previous value on exit from the wimp_poll function.

The default value is DRW_NULLS_CV. The default setting when an application starts is off. Using this method your program code doesn't need to keep track of the current enable null events flag, or have correctly placed code to reset it.

Quitting the application.

The library call to quit an application is drw_wimp_quit. This calls the user function drw_u_quit (and equivalent template 'quit' type functions), in the same way as the BASIC library. The quit type in the C version is given a defined type of drw_quit_flags, which is an unsigned integer type (the type is the bits type defined in the OSLib types header file). The values are

DRW_NO_QUIT (0x1u): means no quit value supplied.
DRW_APP_QUIT (0x2u): means the origin of the quit is from your application, e.g. the user has clicked on the Quit item of the bar menu.
DRW_DESKTOP_QUIT (0x4u): means the origin of the quit is the desktop quit message broadcast.
DRW_QUIT_BOTH (0x6u): Used by the library Discard, Cancel, Save process to identify further action after the Discard or Save icon in a DCS dialogue has been SELECTed. Your application should not use, or need to know about this value.
DRW_DCS_IS_POP_UP (0x8u): Used by the library Discard, Cancel, Save process to identify the type of DCS dialogue. Your application specifies the type when the DCS dialogue box is created. This value means that a mouse click outside the dialogue causes the dialogue to be closed.
DRW_DCS_IS_STATIC (0x10u): Used by the library Discard, Cancel, Save process to identify the type of DCS dialogue. Your application specifies the type when the DCS dialogue box is created. This value means that the dialogue box stays on screen until a Discard, Cancel or Save button is <SELECT>ed by the user, or the dialogue is closed using the CLOSE icon.

[Top]