USER-MANUAL FOR DrWimpC App Builder
Version 0.75 (11-04-06)
Original BASIC DrWimp Library © Andrew Ayre 1996-98
Original BASIC DrWimp Library © Ray Favre May 1999 onwards
DrWimp C Library Implementation © Peter Miller 2012
!DrWimpC DrWimpC App Builder © Peter Miller 2012
Current DrWimpC Web Site.
Caveat 2012: This Manual was written some years ago in hand coded HTML. I have updated it with some additional notes and annotations about such things as using shared libraries with GCC 4 but there is much more to !DrWimpC now and this manual is a much bigger project in itself. Therefore, I am releasing !DrWimpC with this manual which will be progressively updated for the latest !DrWimpC using a web site builder. In the meantime this manual will give a little information on the workings of !DrWimpC although it will still sometimes be out of date. Along with some useful info on the compilation and application distribution processes in DrWimpC App Builder, much of it seems to refer to an application's use of the user functions, prior to the introduction of template functions and defined menus. There is some information on template functions which is supplemented by the material in a more up to date and detailed form in the web site Getting Started and subsequent pages. In addition to the Getting Started pages of the Current DrWimpC web site !DrWimpC has a StrongHelp manual for the DrWimpC library API with a reference to each user function and library function (at least those with a corresponding BASIC DrWimp function - since then protocols such as External Edit and OLE, scrap file handling, window autoscroll, and other enhancements have been added that have further user and library functions which still need documenting).
Requirements
Library Structure Definiitons. OSLib.
- The DrWimpC implementation uses OSLib for its C wimp structure defintions. There is no need to reinvent the wheel or repeat work by defining and naming structures in !DrWimpC that already have perfectly usable (and up to daate!) definitions in the OSLib header files.
A C Compiler and Tools
- The DrWimpC App Builder supports the ROOL C/C++ compiler and tools, and the free GNU GCC compiler and tools.
A Source File Editor
- The C sources are in text files, so any editor can be used with these.The
!DrWimpC program interacts with source editors using the external edit protocol, so to use this facility you will need an external edit capable source file editor. at the time of writing there are two excellent editors on Risc Os, !Zap and !StrongEd that handle the external edit protocol.
A web browser
- To view this help is in HTML format and the Getting Stated On Line Instructions.
!SharedLibs.
- The DrWimpC library uses the shared C library and programs using it must be linked with the Shared C library stubs file. This can be the global stubs file Gstubs produced by Risc Os Ltd, or the one provided with the Castle C/C++ tools, or the libscl file provided with the Risc Os port of GCC.
A Template File Editor
- It is convenient and far easier to design the windows for an application using a template editor than manually writing code to do this. There are several freely available template editors, !WinEd, !TemplEd and !FormEd among them. Personally I have grown accuatomed to using !WinEd, and occasionally !TemplEd.
You will also require a template editor if you want to link C functions to icons in window definitions in a template file.
[Top]
Installation
This consists of copying the !DRWDEF DrWimpC resources and !DrwimpC application and example programs from the archive to your computer's hard drive. The DrWimpC library is supplied inside !DRWDEF.DRW. There are several versions. One for use with the ROOL C Tools, and two for use with GCC 4 - (one for static linking, the other for shared linking).
This release of !DrWimpC and its example programs are compiled with GCC and linked shared and so require the use of !Sharedlibs available as part of the GCCSDK. !DRWDEF should be placed in the same directory as !Sharedlibs.
The method used in the DrWimpC user C source files to refer to included header files in the DrWimpC library is to do so by means of path names, so header files includes are of the form #include "DRW/<header file name>.h". Your own code should reference the DrWimpC library header files in the same way.
OSlib can be downloaded from the OSLib pages at sourceforge.net. OSLib is installed onto your system in a similar way to DrWimpC. Follow the supplied instructions, and make sure that the OSLib obey file and SetVars are also run before using DrWimpC. DrWimpC references OSLib header files using the system path variables set up by these macros.
If you are going to use the free GCC compiler, then download the GCCSDK by following the link to the latest version at the Risc Os Info GCC page. As the GCC instructions indicate, installation is just a matter of copying the !gcc directories in the various elements of the archive onto your hard drive. Also download the base and C Sharedlibs archives and install the !Sharedlibs files as indicated.
[Top]
Introduction ...
!DrWimpC is an application development aid to support an implementation in the C programming language of the popular BASIC library DrWimp. The C library - DrWimpC - contains equivalent functionality as the BASIC version, along with some additional features. This DrwimpC C library implementation aims to minimise the programming work required to handle the wimp interaction of an application by doing as much of the work as it can on behalf of the application. The same method of splitting the WIMP handling and user application actions is used in DrWimpC, that is, DrWimpC handles the WIMP interaction and passes control to user applications via a set of 'user functions' so that each application can carry out actions due to a WIMP event occurring for the application. To avoid name clashes, each WIMP function in the DrWimpC library is prefixed by drw_, and each user function by drw_u_, and both WIMP and user functions are grouped into separate source files according to the WIMP event/function for which they provide support. This helps reduce the code size of the !RunImage file produced by the compilation and linking process. This is also the point where !DrWimpC starts being a useful tool.
With !DrWimpC you can create a new application with default user files in the c source file directory by naming the application in the New Application dialogue and supplying optional information for the application's info window, of the application's purpose, author and version, and specifying the location for storing the new application on disc. Once accepted, many more application details may be specified using the Application Details dialogue, such as whether the application has an icon bar icon, menu and a main window that is opened when the mouse pointer is over the application's icon bar icon, and the select or adjust button is clicked.
!DrWimpC uses a menu system to list all C source files for an application.Once created, the user files can be edited by selecting them from the appropriate !DrWimpC menu - the source files are grouped into lists of standard user files (those beginning with 'drw_u_'), and your own created source files. !DrWimpC communicates with editors using the external edit protocol. Equally, the source files can be edited by loading them directly into an editor yourself.
Note: Since this manual was first written a Project window has been produced and is the main method for working on an application, instead of using the menu system, although that is still available.
An application can be further developed by adding your own source code, and also by using !DrWimpC to add more default user files for editing, according to the WIMP actions that the application responds to.
Compiling and linking of the source code into the final !RunImage can be done by means of the Build, makefiles and make items of the Application Management menu. You can then run the application using the Run item of the same menu, or by the usual method of double clicking on the application icon in a filer window. The Build and Makefiles items cause makefiles to be generated, taking into account the development tool choices you have for this application. !DrWimpC generates make files using either the Castle C/C++ tools or the GNU GCC compiler, link, libfile and make tools. The Application Management menu also has options to time stamp source files to cause their recompilation, debug options to allow debug information to be compiled with individual or all source files, and options to clean up the object file directories.
An additional feature of !DrWimpC and the DrWimpC library is the ability to link C functions to icon definitions in a template window definition by means of the icon name. The functions are grouped together by template file leafname and compiled into object code libraries that can be reused, separately or along with their template definitions, in other applications. See the Template Files and Templates icon bar menu items and Linking Template Definitions to C functions for a description of how the functions are linked to the icon names and called automatically by the DrWimp C library. With this method youonly need to add the functions you need to supply code to handle an event instead of having all the default functions (and C files) created automatically as with the user function method above. This leads to smaller source compiled code but you need to know more about how
the event operates. The user function method also more closely resembles the BASIC DrWimp Library implementation of the code while the template function can be used to write reusable code based on the reuse of the icons in other (application's) templates.
The last benefit has even more to recommend it now that shared libraries are possible using GCC 4.
[Top]
Library Error Handling
All SWIs are called in the 'X' form and an error returned and reported through Wimp_ReportError. Although this leads to a single tasking error report dialoguue, errors form DrWimpC library should not be a regular occurence. So, when they do occur they should be appropriately brought to the user's attention. In that case, a single tasking dialoue box is acceptable. In any case, this is a simlar result to the BASIC DrWimp error handling and alternatives are more complex to implement with not much of a benefit and not the core focus of this release of DrWimpC library (which is to get everything working to a releasable standard).
[Top]
When Using !StrongEd
If you are using !StrongEd with !DrwimpC, I recommend that you use a C like mode for external edit so that you will have the features of the !StrongEd C mode such as syntax colouring and bracket matching. I do this on my system, by copying the external mode in the Defaults.Modes directory into the !StrEd_cfg.UserPrefs.Modes directory and replacing the ModeFile and ModeWhen files by the C mode ModeFile and ModeWhen files, and
placing the line
- fff,(*).**
at the start of the Rules Include section of the ModeWhen file. The !StrEd_cfg is in the same directory as !StrongEd.
[Top]