Return to readme.doc CVS log

Up to [OS/2 SDKs] / os232sdk / toolkt20 / c / samples / template

Annotation of os232sdk/toolkt20/c/samples/template/readme.doc, revision 1.1

1.1     ! root        1:     SAMPLE PRESENTATION MANAGER APPLICATION TEMPLATE
        !             2:     ================================================
        !             3: 
        !             4: The sources contained here are designed to serve as a template for
        !             5: your PM application.  These source files contain the overhead
        !             6: routines necessary to create a PM application as well as stubs
        !             7: for the basic menu items that all applications should have.  The
        !             8: source files are organized so that only a few of the files need to
        !             9: be modified; most of the source files can be left alone.  All of
        !            10: standard initialization and general functionality routines are placed
        !            11: in separate source files.  Since most applications will not need to
        !            12: change these routines, these files do not need to be changed.
        !            13: 
        !            14: 
        !            15:     ORGANIZATION OF SOURCE FILES
        !            16:     ============================
        !            17: 
        !            18: Here is list of the source files included in the template application
        !            19: and their general purpose.  All filenames have been limited to four
        !            20: characters so that you may add a prefix to the filenames to delineate
        !            21: which ones have been modified for you application.
        !            22: 
        !            23:     main.h - application constants
        !            24:     xtrn.h - external variable and function declarations
        !            25:     help.h - help panel ids
        !            26:     dlg.h  - dialog box constants and item ids.  This file is designed
        !            27:              to be used with the dialog editor.
        !            28: 
        !            29:     main.c - main function, main window procedure, basic menu handler
        !            30:     init.c - initialization and Exit List processing routines
        !            31:     file.c - routines for processing File menu items
        !            32:     edit.c - routines for processing Edit menu items
        !            33:     user.c - functions for processing menu items and messages
        !            34:              specific to the application
        !            35:     dlg.c  - application specific dialog boxes
        !            36:     help.c - help manager functions
        !            37:     pnt.c  - routines for painting the main window
        !            38:     prnt.c - routines for printing
        !            39: 
        !            40:     main.rc - main resource file containing menus, stringtable, etc.
        !            41:     help.rc - resource file for help panels
        !            42: 
        !            43:     main.ipf - main help text file, contains the link to the others
        !            44:     file.ipf - help text file for the file menu items
        !            45:     edit.ipf - help text file for the edit menu items
        !            46:     menu.ipf - help text file for the application defined menu items
        !            47:     dlg.ipf  - help text file for the dialog boxes
        !            48:     help.ipf - help text file for the help menu
        !            49: 
        !            50:     sample.mak - make file for the sample application
        !            51:     sample.def - module definition file for the sample application
        !            52: 
        !            53: 
        !            54: Also included are two blank headers for use in your source files.
        !            55: 
        !            56:     funchead.c - blank header used before each function
        !            57:     head.c     - blank header used at the beginning of each source file
        !            58: 
        !            59: 
        !            60:     ORGANIZATION OF THE SAMPLE TEMPLATE
        !            61:     ===================================
        !            62: 
        !            63: Most of the general setup and overhead code is located in the main.c
        !            64: file.  Since this code is standard for all PM applications, you
        !            65: will probably not need to modify main.c at all.  Main.c
        !            66: contains the window procedure for the main window (MainWndProc())
        !            67: as well as the routine for processing the WM_COMMAND message
        !            68: received by the main window (MainCommand()).  MainWndProc() handles
        !            69: all the messages that every window must handle.  MainCommand()
        !            70: handles all of the WM_COMMAND messages posted by all of the standard
        !            71: menu items and by calling the appropriate routine to process the
        !            72: command.  There is one routine for each standard menu item and
        !            73: they are located in separate source files, one file for each menu.
        !            74: 
        !            75: While these two routines handle all of the standard messages and
        !            76: menus, some additions will be required to one or both when you add
        !            77: your own menus or other features. Rather than have you modifying the
        !            78: file that shouldn't need to be changed, the parts you can modify have
        !            79: been moved into their own file, user.c.
        !            80: 
        !            81: User.c contains the user defined version of the window procedure
        !            82: (UserWndProc()) and the WM_COMMAND message handler (UserCommand()).
        !            83: These two routines are called by the main routines if the message was
        !            84: not one of the standard messages or menu.  For example, the user window
        !            85: WM_COMMAND processor is called if the message was not posted by one of
        !            86: the standard menu items.  By placing UserWndProc() and UserCommand()
        !            87: into their own file, you can now add the processing necessary for your
        !            88: application without the having the standard processing code cluttering
        !            89: up the routine.
        !            90: 
        !            91: 
        !            92: 
        !            93:     USING THE SAMPLE TEMPLATE
        !            94:     =========================
        !            95: 
        !            96: If you compile and link the sample application now, it will create an
        !            97: application that will run.  Although the application will not do
        !            98: anything, it is worth building the application in order to test your
        !            99: build environment and to see what a basic PM application looks like.
        !           100: 
        !           101: The sample application has only three menu items, File, Edit, and Help.
        !           102: The File menu contains commands for use on documents, e.g. opening a
        !           103: document or saving it to disk. The Edit menu contains commands for
        !           104: processing data in a document, namely cutting, copying, and pasting
        !           105: data to and from the clipboard.  The Help menu contains the standard
        !           106: commands for dealing with the help manager.
        !           107: 
        !           108: The routines for processing the standard menu commands are located in the
        !           109: *.c source files, where * is the name of the menu (e.g. File.c for the
        !           110: File menu).  The source file contains one routine for each
        !           111: menu item and the routine is named with the menu item name prefaced
        !           112: by the menu name.  For example, the routine that processes the New
        !           113: menu item of the File menu is FileNew().  The routines currently
        !           114: perform any actions which most applications will also take and then
        !           115: leave it up to you to add any application specific code.  The
        !           116: FileOpen() routine, for instance, calls the standard File Open dialog
        !           117: to retrieve a file name and opens the file for reading.  All you need
        !           118: to do is supply the code to read in the file.  You will need to
        !           119: supply routines to process all of the menu items whose commands are
        !           120: in these files.  Consult your CUA Style Guide if you have any questions
        !           121: as to the function of these menus.
        !           122: 
        !           123: You will also need to add any other menus which your application will
        !           124: use.  First add the menu item id values in the main.h file.  Next add
        !           125: the menu resource to the main.rc file. Now, add the code to process
        !           126: the WM_COMMAND messages posted by the menus to the UserCommand() routine
        !           127: in user.c.  Add the menu item id values to the switch statement and
        !           128: include any menu item processing code there.
        !           129: 
        !           130: Should you wish to process any of the messages sent to the main
        !           131: window which are not processed by the standard window procedure, you
        !           132: can add these to the UserWndProc() routine in user.c.  Add the
        !           133: message id to the switch statement along with the routines for
        !           134: processing the message.  Make sure that the default case calls
        !           135: WinDefWindowProc().
        !           136: 
        !           137: Any other initalization, such as command line processing, can be done
        !           138: by adding code to the Init() routine in init.c.  If there is additional
        !           139: processing you want done when the main window is created, add these
        !           140: routines to the InitMainWindow() function of init.c.
        !           141: 
        !           142: Remember to add new help screens for any menu items you add to menu.ipf
        !           143: and for any new dialog boxes you create to dialog.ipf.
        !           144: 
        !           145: Finally, change the the name of the source files you modified to reflect
        !           146: the name of your application.  If you use this template for more than
        !           147: one application, you will need an easy way to tell which source files
        !           148: belong to which application.  Embedding the identification of the
        !           149: application within the name of a source file will help you keep
        !           150: track of which application that source file is a part. Now if you use
        !           151: this template for more than one application you will be able to quickly
        !           152: discern the sources for each application, even if you have copies
        !           153: of the sources to more than one application on the same disk.
        !           154: 
        !           155: To tag the source files with an identifier for each application but
        !           156: still retain the identity of the source file, you should implement
        !           157: a prefix_suffix naming scheme for your source files.  The prefix
        !           158: should be a three letter abbreviation for your application name
        !           159: while the suffix should be the current name of the file.  All
        !           160: source files of the same application will then begin with the same
        !           161: three letters. Yet they will still contain the original name of
        !           162: the file so that the contents of the file can easily be determined
        !           163: by name.  For example, suppose you have two applications,
        !           164: APP1.EXE and APP2.EXE. You would know that the files AP1_INIT.C and
        !           165: AP1_DLG.C both are part of application 1.  You also know that
        !           166: AP1_PRNT.C and AP2_PRNT.C contain the print routines for each
        !           167: application.
        !           168: 
        !           169: The make file and module definition file should be changed to use the
        !           170: name of your application, not just an abbreviation.  Using the
        !           171: above example, your make file for application 1 would be APP1.MAK and
        !           172: the module definition file would be APP1.DEF.
        !           173: 
        !           174: Remember to change all references to files in your make file to
        !           175: match the name changes you make.  If you change header file names,
        !           176: also make sure to change all #include statements in the source
        !           177: and resource files that reference those header files.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.