![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to readme.doc CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [OS/2 SDKs] / os232sdk / toolkt20 / c / samples / template|
Return to readme.doc CVS log | Up to [OS/2 SDKs] / os232sdk / toolkt20 / c / samples / template |
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.