Documentation for the To-Do List Component
The to-do list component was modeled exactly after the to-do list in PowerBuilder 7. The best effort was made to include all the functionality available in PB's to-do list. To use the to-do list in your PFC application, just create a new window inherited from w_todolist. Then simply open the to-do list like any other window. For the most part, the to-do list should be very easy to use and to implement but some of the features like hyperlinks and the save/restore functionality require some more detailed explanation.
HyperLinked Entries
The to-do list can have two types of entries, linked and unlinked. A unlinked entry is an inactive reminder, while a linked entry can be clicked and the user will be directed to the area of the application where he can fulfill the entry's task. How you implement linked entries is up to you. Two properties are maintained with each linked entry, stringparm and doubleparm. When using the of_addentry function you may pass in values for these properties. When a user clicks on a linked entry, the w_todolist.todolist_followlink event is triggered. The stringparm and doubleparm properties of the clicked entry are passed as arguments to this event. It is up to you, the developer, to code in your descendant to-do list, the logic that will parse these properties and determine what the link does. In the example application, the class name of a window is stored in the stringparm property. When the user clicks a linked entry in the example application, the to-do list opens a window of that type or class. This is just an example, however. You can store any information in the stringparm and doubleparm properties and do anything you want with them in the todolist_followlink event. The user can also add a linked event through the right mouse popup menu. It is also up to you to determine what this new entry is linked to. When the user clicks on the "Add Linked" menu item, the w_todolist.todolist_addlinked event is triggered. The stringparm and doubleparm properties of the new entry are passed by reference to this event. You should populate these arguments and then return CONTINUE_ACTION or 1 from this event. You may also return PREVENT_ACTION or 0 in order to prevent the entry from being added. If you did return CONTINUE_ACTION from this event, the linked entry will be added and the user will have the opportunity to add the entry's text.
Saving and Restoring Entries
Saving and restoring the to-do list entries is a little complex. The functionality to save and restore entries has been externalized from the to-do list window. What does that mean? Well, the window w_todolist does not save its entries but a separate object, n_cst_todoliststatemanager, is responsible for saving and restoring the entries. Why was this done? Two reasons:
So how does it work? The object n_cst_todoliststatemanager has two virtual functions, of_savestate and of_retrievestate. You must inherit an object from n_cst_todoliststatemanager and implement of_savestate and of_retrievestate. The of_savestate function takes one argument, as_state. This is a tab-delimited string containing the data as it is stored in the datawindow d_todolist. In of_savestate, you must write this data in any form you wish to your persistent storage (i.e. registry, database, file). The of_retrievestate function also takes one argument, as_state BY REFERENCE. In of_retrievestate, you must populate as_state with tab-delimited data in the format of d_todolist. There are two corresponding functions on w_todolist, of_savestate and of_retrievestate. Both of these functions take, as an argument, an instance of your to-do list state manager. To initiate a retrieve you would call of_retrievestate(lnv_mystatemanager). To initiate a save you would call of_savestate(lnv_mystatemanager). The example application includes a ready-made state manager to save/restore entries to the registry, n_cst_todoliststatemanager_registry. You may use this object if it fits your needs, otherwise please use it as a guide as how to create your own custom state manager. The example application has been designed to save/restore state to the registry. Please refer to it for more information.
Miscellaneous Info
You may wish to integrate your to-do list with the PFC application manager (n_cst_appmanager) so that you may get reference to the to-do list from anywhere in your application. You can do this just like it was done in the PFC for the frame window, i.e. of_setframe and of_getframe. An example of this was done for the example application.
You may also wish to add an entry to the to-do list when it is not open. You can accomplish this by adding a method (of_addentry) to your state manager. This method should add an entry to your persistent storage. At runtime you should determine whether or not the to-do list is open. If the to-do list is open then add the entry directly to the to-do list, otherwise instantiate your state manager and add your entry through it.
One difference in behaviour between this to-do list and PB 7's. If the user adds and entry but does not add any text, the entry is deleted. Along the same lines, if the user edit's an entry and deletes all the entry's text, that entry is subsequently deleted. The bottom line, an entry must contain text or else it will be deleted.