#ifndef OLC2_H #define OLC2_H //***************************************************************************** // // olc.h // // My first go at OLC was during the pre-module time, and it really wasn't all // that well put together in the first place. This is the second go at it... // this time, OLC is more like some general functions that make it easy to do // online editing, rather than a full system. It will be amenable to adding // new extentions to the general OLC framework from other modules, and it will // essentially just be a bunch spiffier. // //***************************************************************************** // // prepare the OLC framework for use void init_olc2(); // // Set up a new OLC. OLCs can be stacked on top of eachother (e.g. room edit // could call extra description edit. After the extra description edit is // exited, room edit will continue). If this is the only OLC in use, OLC mode // will automatically be entered. Below are descriptions of the paramaters the // following function takes, and the form they should be: // // menu: This is a function that displays the current OLC menu to the socket. // void menu(SOCKET_DATA *sock, datatype *to_display) // // chooser: This is a function that takes in the menu option that the socket // wishes to select. The values q and Q are reserved by the OLC handler // for quitting. The chooser is responsible for prompting the socket for // appropriate arguments after a menu option has been selected. There are // three types of values that can be returned: // -1 invalid option // 0 Valid choice, but we do not need to enter the parser. This // would be returned, for instance, if a new do_olc was called, // or if a toggle on/off menu option was selected. // >= 1 a numeric value representing the field we are editing. This // will be passed to the modifier() function to perform changes // after an argument is passed in. // the chooser function is of the form: // int chooser(SOCKET_DATA *sock, datatype *to_edit, const char *option) // // parser: This function is used to parse an argument, given a choice from the // menu. The choice is provided by the chooser() function, and an argument // is supplied afterwards. TRUE should be returned if the argument was // valid and the command was a success, and FALSE if it was not. // The parser takes the form: // bool parser(SOCKET_DATA *sock, datatype *to_edit, int choice, // const char *arg) // // copier: This is a function that returns a deep copy of the data we are // editing. The data is not worked on, directly. Rather, a copy of it // is made and edited. If the changes are accepted at the end of OLC, they // are copied back over to the thing we were editing. This parameter can // be NULL if the data is to be worked on directly. The function is of // the form: void copier(datatype *thing_to_copy) // // copyto: This copies the data of one thing over to another datastructure of // the same type. This parameter can be NULL if the data is to be worked // on directly. This function takes the form: // void copyto(datatype *thing_to_copy_from, datatype *thing_to_copy_to) // // saver: After OLC is exited, we'll typically need to save the changes to disk. // this is the function that should be called to save all of the changes // that have been made. Saver can be null if changes are not to be saved // to disk after they have been made. This function takes the form: // void saver(datatype *working_copy) // // deleter: this is a function that will delete the working copy of our data. // This parameter can be NULL if the data is to be worked on directly. // This function takes the form: // void delete(datatype *working_copy) #define MENU_CHOICE_CONFIRM_SAVE (-2) // this define for internal use only! #define MENU_CHOICE_INVALID (-1) #define MENU_NOCHOICE (0) void do_olc(SOCKET_DATA *sock, void *menu, void *chooser, void *parser, void *copier, void *copyto, void *deleter, void *saver, void *data); //***************************************************************************** // To keep a general "look and feel" to OLCs, a couple functions have been // provided to display some features of an OLC in a standard manner. //***************************************************************************** // // Display a bunch of options in a tabular form. The table will have num_vals // elements, and num_cols of those elements will be displayed per row. void olc_display_table(SOCKET_DATA *sock, const char *getName(int val), int num_vals, int num_cols); // // Same deal as olc_display_table, except that it takes in a list of strings void olc_display_list(SOCKET_DATA *sock, LIST *list, int num_cols); #endif // OLC2_H