Introduction !DrWimpC Features DrWimpC library Examples


!Create


The !Create Example Illustrates ... Source Files and Functions Used

Manual creation of windows and icons. Simple saving of files by means of a save window. Use of an application header file. Minor but significant difference in the manual initial setting the window title (compared to the BASIC DrWimp library).

!Create Overview.

Wimp Lib Actions

  • Data Save Protocol

Standard User Files.


.

Overview



Many applications take advantage of template files to define definitions of the windows they use. However, you can create a window definition manually using functions (and default definition structures for windows and icons) in the DrWimpC library. This example illustrates this by creating a small save box window. In contrast to the BASIC DrWimp library, where a single function with sixteen parameters, some flag words - so bit values must be set up, is used, the DrWimpC library provides a set of functions to initialise the various window flag words, and title data, etc. If no window structure pointer is passed to these functions then the functions assume use of a default structure inside the DrWimpC library.

Globally used data items are grouped together into the create_app_data structure, whose definition is placed in a header file which is stored in the application's header directory.

[Top]

Application Data





static create_app_data cd;

The three icons used in the save file window (representing the drag, write and ok icon numbers, are grouped into a data structure, create_app_data. An instance of this structure is statically declared at the beginning of drw_uw_init.





static char _savetype[5];

The character string of the hex value of the file type to save. This is also statically dec;ared at the start of drw_uw_init.

[Back to the Function List]
[Top]

void drw_uw_init(drw_uw_data *uwd)


The first thing this function does is to set the user wimp data application data pointer to point to the statically declared create_app_data structure (cd) so that it can be accessed in functions in other source files in the application.

Next, the default window definition structure inside the DrWimpC library is initialised by copying default values into it by the call drw_wimp_copy_default_wdefn(NULL). The NULL pointer indicats that the default window definition structure is to be used. The structure's type is wimp_window, an OSLib type defined in OSLib's wimp.h header file. The default area used by DrwimpC is the wimp block area, whose size is given in the new application dialogue, and is passed between functions as a byte * pointer. (byte is a type also defined in OSLib header file types.h).

Next the various parts of the window definition are set to the values for the save window to be created. These are, in turn,

There are other functions for initialising any other parts of the window definition. Their prototypes are in the DrWimpC library header file drwWcreate.h.

The window is created, and its handle stored in the user wimp data's bar window handle. The window is opened when SELECT is clicked with the mouse pointer is over the application's icon. (The default drw_u_mouseclick function in file drwUmouse already contains code to check for this mouse click and open the bar window, so nothing more needs to be done to open the window).

Note: The window title initialisation is handled in a different way to the way BASIC DrWimp library does it. This is due to the way that literals are handled in C programs. The window title data must be indirected, and since it can be changed, cannot be a simple pointer to the title value passed to drw_wimp_init_wtitle() because if this is a literal, and you try to change it, the program could crash. So, drw_wimp_init_wtitle (re)allocates memory from the malloc stack for the title, and copies the title value into it. If you use drw_wimp_init_wtitle() you must call drw_dealloc_ind_title_data to deallocate this memory when you delete the window definition. In this example, the call to drw_wimp_init_wtitle() is done in drw_uw_closedown.


Next, the icon definitions are added to the window definition. In a similar way to the window definition, this is done by a series of function calls to initialise an icon data structure before its values are used to create the icon definition. If no icon data structure is used (i.e. NULL is passed to the functions in place of a valid icon structure pointer, then a default structure inside the DrWimpC library is used, as in this example).

Note: As for the window title, there are differences in the way the DrWimpC library allocates memory to the indirected data, such as the icon's text, of an icon definition to the way that the BASIC DrWimp library does it. The BASIC version uses the BASIC DIM statement, whereas the DrWimpC library uses malloc. This means that the indirected data can be resized when it's value is changed to be larger than its current value. Additionally, since the indirected data could already be part of another C structure (that exists for the lifetime of the sprite) then you may not actually need to allocate memory, but can pass a pointer to the value, thus avoiding unnecessary use of the C program's malloc stack and duplication of data. For this purpose, DrWimpC provides a function to set flags to indicate whether an icon's data should be allocated memory, or not. This call should precede a set of function calls used to iunitialise an icon definition prior to creating it. the function is

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

The flag meanings when set, in order, are

The !Create example calls drw_wimp_set_imem_flags before creating the icon definitions.

For each icon to be created, the icon structure is initialised as follows

The prototypes for all functons that are used to initialise or set icon data flags and values are in header files drwWiinit and drwWiflags.

[Back to the Function List]
[Top]

char *drw_u_savefiletype(wimp_w window, char *ftype)


The !Create example creates a simple save window. When the file type sprite icon is dragged to a filer window, or the <RETURN> key is pressed, the DrwimpC library calls this function to ask your application for the file type of the file to be savedas a string value representing the value in hexadecimal of the file type. If no file type is returned the DrWimpC library does not take any further action and no file is saved. However, by returning a vlid file type, you indicate that your application intends to save the file with the returned type. In this example, the text file type (FFF) is returned using the statically declared _savetype string. It is statically declared so that it is still in existence after returning from the function, and so can be validly referred to by the DrwimpC library.

[Back to the Function List]
[Top]

void drw_u_saveicon(wimp_w window, wimp_i *drag, wimp_i *write, wimp_i *ok)


During a save box data save process, the DrwimpC library calls this function to request the icon number in the window where the save initiates of the icon being dragged, the icon where the name of the file to be saved has been entered, and the ok button that can initiate the save process (instead of an icon drag). Note that the parameters for returning the values are pointers. In this example, the icon numbers have been stored in the create_app_data structure when the icons were created, so if the bar window is the window where the save originated, the values are returned.

[Back to the Function List]
[Top]

int drw_u_savedata(int myref, char *filename, char *leafname, wimp_w window)


When the data save process results in the file being saved, the DrwimpC library calls this function to allow your file to do the saving of the file. The return value indicatws if you have saved the file (q = 1), done nothing (q = 0), or encountered an error (q = 2).

[Back to the Function List]
[Top]

void drw_uw_closedown(void)


This function is called to carry out any tidy up operations before an application exits. It is called after the application's poll loop has been exited. In this example the only thing that is needed is to deallocate the memory used for the indirected window title, so drw_dealloc_ind_title_data is called. Lastly, drw_wimp_closedown should always be called in case the DrWimpC library still has outstanding closedown operations to do.

[Back to the Function List]
[Top]