To this point most of the abilities of the Code Builder functionality of Retro C IDE has been fairly static, create the main window, add menus, and add objects. The call back functions make it much more robust. The TUI library menus and buttons allows for automatic calling of additional C functions. These functions can be included in the main code file, or one additional header file and associated C or Object file can now be included in the IDE for Code Builder. Let’s take a look.
The new Header Files group sits under the Target System group. The target system selection automatically selects the proper TUI library header file (the set of five radio buttons in the group), and also two other standard header files stdio.h and conio.h are also activated by default. The bottom two check boxes are the User Header file and User Code selections. The header file will be written into the source code with the other header files, and the User Code will be incorporated into the call to the compiler so that any of it’s functions can be used as callback functions with menus or buttons.
To add a header file and C or Object file simply click the appropriate check box and a file dialog will pop up and you can select a .h for header file (this should be from the include directory for CC65) for the User Include, or .C or .O for the User .C/.O code. If you select a .O file you need to be sure it has been compiled for your selected target system. If you select a .C file it will also be compiled with the code file generated by the IDE.
As an example bar.c is a file with two functions foo(); and bar(); and bar.h is the include with the function prototypes. These will be used in the example that follows. The bar() function writes a string to the screen at 2, 10 waits for a key press then erases the string. The foo() function uses the TUI library messagebox() function to show the “Foo is in bar.c” message.
There are two ways invoke these functions, a call back from a menu item or from a button object. Currently both rely on setting up callback functions in the menu system first. To do this a menu is set up as describe in the previous menu post, click add menu or add sub menu item. Below is a sample menu that can be used for or foo, bar functions.
In the earlier post the only call back function that was available was the rci_quit function which triggers exiting the menu system and out of the application. Show below is a new dialog that appears when clicking the Call Back button to assign functionality to a menu item, which is the real power of the TUI library and Retro C IDE combination.
There are now 5 options for call back functions.
- Process all objects – which allow the user to cycle through all objects (built in)
- Process one object – processes only the selected object (user selected object)
- Quit – uses the rci_quit built in function to exit the application
- None – does nothing (mostly for parent menu item with sub items)
- User Code – provides a function shell and the user can write code
The Quit menu item in the sample menu has been assigned the Quit function. Let’s see how to assign the foo() function from bar.c to the Foo menu item. First select Foo menu item in the treeview control and click the Call Back button. When the Call Back form is displayed click on the User Code button. This will populate the code text box with a shell of a function call as seen below. The function name is generated by the IDE, and is comprised of rci_menu which is used to indicate the it is created from the Retro C IDE menu system. the _Foo_ comes from the menu item text. Finally the _0 is from the index of the Foo menu item to ensure this function name is unique incase of another menu item named Foo. Because TUI library call back functions are implemented with the use of null pointers and the prototype includes the passing of a pointer to the window it is being called from the parameter void *ptr is included. The good thing is the user doesn’t need to worry about this, but does make access to all object in the window to the user. In order to convert the null pointer to a TUI winow the Tgui_Window *win; and win=ptr; are automatically included. In our example win won’t be needed but know it’s there.
To call the foo() function simply add the code foo(); in the function and click the OK button.
The same can be done for bar():
For an Atari Example of this application it would look like the following. After clicking the Play button on the Retro C IDE tool strip the code is generated, saved, compiled and the Atari emulator is called:
When the Foo menu item is selected:
When the Bar menu item is selected:
The next post will show how to leverage these call back functions from button objects.