home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_progs / prog_c / skel.lzh / SKEL / SKEL.DOC < prev    next >
Text File  |  1991-08-16  |  12KB  |  242 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6. "z
  8.  
  9.                  Skeleton Workbench Application
  10.                           by Joel Swank
  11.                          January 9, 1989
  13.  
  14.  
  15.  
  16.     The Skeleton  Workbench  Application  is  my  attempt to make
  17. writing  workbench  applications  (almost) as easy as writing CLI
  18. applications.   When  I began adding Intuition interfaces to some
  19. of  my  CLI  utilities  I found that I needed esentially the same
  20. routines  in  each.  So I decided to make a skeleton program that
  21. provides  all  the  basic routines needed by most applications. I
  22. now  have  a  'Skel'  directory  that  I  copy  to  start   a new
  23. application.  Then  I rename and modify each of the files to suit
  24. the new application.  
  25.    The Skel directory contains the following files:
  26.  
  27.      * makefile: File to compile Skeleton using Aztec C.
  28.      * skel.c:   Mainline, initialization/termination,
  29.                  Gadget and Menu handling.
  30.      * skwindow.h: Data structures for main window.
  31.      * doargs.c: Agrument processing for Workbench and CLI.
  32.      * abouthelp.c: Help window and About Requester processing.
  33.      * helpwin.h: Data structures for help window.
  34.      * skel.info: Tool icon for workbench startup.
  35.  
  36.    Following is   a   description  of  the  Skeleton  and  how  I
  37. customize it  for a new application.  
  38.    I rename  skel.c  and  edit it to be the new main routine. The
  39. main()  routine  first sets up any defaults needed. Then it opens
  40. any   libraries  that  are  needed.  Next  it  calls  either  the
  41. Workbench  or  CLI argument routine. Next it sets up the gadgets,
  42. opens  the  main   window,  and  attaches  the  menu. Finally, it
  43. writes the window text and waits for a message from Intuition.  
  44.    The done()  subroutine  is  the termination routine. It closes
  45. or  frees everything opened or allocated by the program. Whenever
  46. I  add  something  to  the  initialization,  I add a coresponding
  47. entry  to  done().  This  is very important since AmigaDOS has no
  48. resource  tracking. If a program allocates a resource and doesn't
  49. free  it,  that  resource  is  gone  until  next  boot.  The done
  50. routine  is  called  from  wherever  program exit is required. It
  51. accepts  a  return  code  that  is  passed to the exit routine to
  52. become  the error code for the program. Notice that done() checks
  53. to  see  if a resource is allocated before closing or freeing it.
  54. This  allows  it  to be called at any time and it will only close
  55. that  which  has  been  opened.  For  this  to work, all resource
  56. pointers  must  be set to NULL before  initialization, and set to
  57. NULL if they are closed anywhere else in the  program.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.    The main  loop  waits  for  an  IDCMP message to arrive at the
  67. main  window message port. When one does, it uses the Class field
  68. of  the  message  to determine what type of message was received.
  69. It  only  reacts to CLOSEWINDOW, GADGETUP, and MENUPICK messages.
  70. There  are  lots  of  other  types  that might be used. I can add
  71. cases  for  these  here  and  add  the  corresponding  bit to the
  72. IDCMPFlags  of the NewWindow structure before opening the window,
  73. or  use  the  ModifyIDCMP()  subroutine  to change the IDCMPFlags
  74. after the window is open.  
  75.    The CLOSEWINDOW  message  just  causes  done(0)  to be called.
  76. This   message  is  the  result  of  the  user clicking the Close
  77. Gadget.   Of  course,  the  WINDOWCLOSE  bit  must  be set in the
  78. NewWindow Flags field for this gadget to be created.  
  79.    A GADGETUP  message  indicates  that  user has selected one of
  80. the  gadgets  in  my  gadget list. I use the RELVERIFY flag in my
  81. boolean  gadgets so that the user must click and release over the
  82. gadget  to  activate  it.   The  IAddress  field  of  the message
  83. contains  the address of the Gadget structure of  the gadget that
  84. was  selected.   I compare this to a list of my gadget addresses(
  85. a  list  of 1 in skel) to see which was selected. The only active
  86. gadget  in  Skel  is  the  'GO'  gadget  which causes the do_it()
  87. routine to be executed. I can add checks for more gadgets here.  
  88.    Another type  of  boolean  gadget  I can use is a TOGGLESELECT
  89. gadget.   These gadgets are toggled on and off each time the user
  90. clicks  them.  The  current state is kept by intuition and can be
  91. read  any  time by testing the SELECTED bit of the Flags field of
  92. the  Gadget  structure.   No  message  is  generated  when  these
  93. gadgets are clicked.  
  94.    A MENUPICK  message  arrives  each time the user brings up the
  95. menus  for  my  window.  The message Code field contains a number
  96. indicating  which  menu was picked. The processing of a menu pick
  97. is handled in the do_pick() subroutine.  
  98.    The do_pick()   subroutine  determines  which  menu  has  been
  99. selected.   It uses the standard macros to break the message code
  100. into  the  menu  number,  item  number,  and  subitem number. The
  101. proper  routine  is  selected  with  a  series  of  nested switch
  102. statements.  Menus  and  items are numbered from zero starting in
  103. the  upper  left.  The  Project  menu  has 4 items, each of which
  104. cause  the  execution of a routine. The Options menu has only one
  105. item  that  is  an example of using MUTUALEXCLUDE subitems. I can
  106. ignore  the  messages  for  these items because Intuition totally
  107. handles  turning  on  and off the check marks as the user selects
  108. options.  All I have to do is test the CHECKED bit in the SubItem
  109. Flags  field  to  see  which  item  is selected.  The only time I
  110. might  want  to  do something in response to a message for one of
  111. these   items   is   if   the  option  being  selected  needs  an
  112. initialization   routine   to   be  run.   After  processing  the
  113. selection,  I  use the ItemAddress() subroutine to get the actual
  114. address  of  the menuitem structure and get its NextSelect field.
  115. This  is  either the number of another selection to be processed,
  116. or  MENUNULL.  Selection  processing repeats until all selections
  117. in the chain have been processed.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.    The do_it()  subroutine  is  the main action routine and it is
  127. activated  by the GO gadget. It first checks the options and then
  128. calls  off_gads().  off_gads()  disables  all  gadgets except the
  129. STOP  gadget.  In  order  to  do  this  properly I must first use
  130. RemoveGList()  to  remove all the gadgets from the window. Then I
  131. can  make  any  changes  to  the gadgets. I have made a couple of
  132. macros  (OffGad  & OnGad) to set and clear the GADDISABLED bit in
  133. the  Gadget structure. There are Intuition subroutines to do this
  134. (OffGadget()  and  OnGadget()),  but  these routines also refresh
  135. the  image of each gadget. It is more efficient and more visually
  136. pleasing,  when  changing  several  gadgets,  to  to make all the
  137. changes  and  refresh  all  the  gadgets at the same time.  I use
  138. AddGList  to put them back in the window, and then RefreshGlist()
  139. to  refresh  the  image  of  all  gadgets.  Some  gadgets are not
  140. redrawn  properly unless they are drawn on background color, so I
  141. use  RectFill()  to  clear  the  window  first.  Notice  that thr
  142. redraw_scr()  subroutine  is  actually  part  of  on_gadds()  and
  143. off_gads()  and  should  not be called elsewhere. Off_gads() also
  144. removes  the menus from the window so that the user cannot select
  145. them while do_it() is running.  
  146.   After adjusting  the gadgets do_it() enters a loop of drawing a
  147. graphic  and  checking  for  a message at the window port. Notice
  148. that  I  cannot  wait on the port this time because I have things
  149. to  do. So I have to call GetMsg() until I get a non-NULL pointer
  150. back.   I  only  recognize  the  CLOSEWINDOW  and  Stop  gadgets.
  151. CLOSEWINDOW  executes  done(). On Stop I exit the loop and finish
  152. do_it()  with  the   off_gads()  subroutine. It swaps the gadgets
  153. back and attaches the menu.  
  154.   The Open  menu  item  executes  the do_open subroutine. This is
  155. where  I normally would have my interface to a File Requester and
  156. the  open  of the returned filename. Instead Skel has just a test
  157. of my standard 'Open Fail' error Requester.  
  158.   I have  included an _abort() routine. This routine is called by
  159. the  Aztec  Chk_Abort  routine.  Chk_Abort is called by the Aztec
  160. I/O  routines  to  check for the cancel signal. It calls abort to
  161. clean  up  and  exit when it detects cancel.  If the program uses
  162. none  of  the  Aztec  I/O  routines  and  doesn't call Chk_Abort,
  163. _abort()  is  not needed. The only other use for _abort() is with
  164. Manx's  source  level  debugger (SDB).  SDB calls _abort() when I
  165. use  the q command to exit the program early.  If I put a call to
  166. done() in _abort() the q command will release all my resources.  
  167.   The doargs.c  file  contains  a  subroutine  to  get  workbench
  168. arguments  and  a  subroutine  to  get CLI arguments. getWBargs()
  169. finds  the Workbench startup message and reads in the icon of the
  170. first  argument  in  the  argument list. This is the icon used to
  171. start  the  program.  It  should  be  a  Tool  icon.  It may have
  172. parameters  set in the ToolTypes array.  I use the FindToolType()
  173. subroutine  to  check for my 3 possible tooltypes. FindToolType()
  174. is  case  sensitive,  so  to change the DELAY argument 'DELAY=20'
  175. must  be  entered,  'delay=20'  won't work.  I could also use the
  176. MatchToolValue()  subroutine  to  check  for specific values of a
  177. ToolType.   The  user  can  use  Workbench  Info tool to edit the
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186. ToolTypes   array.    In   order   to   read  the  arguments  the
  187. icon.library  is  needed.  Since getWBargs() is the only place it
  188. is  needed,  I  open  and  close  it here and it is not closed in
  189. done().  getCLIargs()  scans the C argument  array for the same 3
  190. arguments.  There  is also an empty subroutine called _wb_parse()
  191. in  this  file. It is a dummy to keep the Aztec subroutine of the
  192. same  name  from  being  included  from the library.  _wb_parse()
  193. scans  the ToolTypes array for a Window specification and opens a
  194. window  if it finds one. Since I am handling the ToolTypes array,
  195. and opening my own window, I don't need the Aztec routine.  
  196.    The files  abouthelp.c and helpwin.h contain everything needed
  197. for  two  items I always have on my Project menu, About and Help.
  198. about()  displays  a requester with program name, version, author
  199. and  date.  help()  Opens  its  own  full  sized window and pages
  200. through  an  array  of text lines. The text is stored as an array
  201. of  pointers  to  lines of text. A NULL pointer ends the array. A
  202. line  with  only  a formfeed is a signal to stop and wait for the
  203. user  to  click  the  'MORE'  gadget. This file also contains the
  204. text  structures  for  my  AutoRequest()  error requesters. I use
  205. single  and  multi-line  requesters  to inform the user of errors
  206. and other important information.  
  207.    The skel.info  file  is  a tool icon that can be used to start
  208. skel.  I edit this file using the icon editor to make an icon for
  209. the  new  application. I use the Workbench Info menu selection to
  210. edit  the  ToolTypes  array  and add any entrys needed by the new
  211. application.  I  then  rename  it  to  match  the name of the new
  212. command.  
  213.    The remaining   file,   skwindow.h,   contains  all  the  data
  214. structures  defining  my main window, all its gadgets and all its
  215. menus.  This  code  was  generated  with  PowerWindows 2.0. I use
  216. PowerWindows  to  create  all my window definitions. PowerWindows
  217. makes  designing  and  editing  Screens  and  windows and all the
  218. trimmings  very  easy.  I  always  keep my PowerWindows generated
  219. source  unedited,  so that it is easy to alter the definition and
  220. generate  new source. If you don't have PowerWindows, you can use
  221. skwindow.h as a guide for creating your own window.  
  222.    There are  a  lot  of  other  things  needed  to  flesh out an
  223. application.   One  of  the  most  common  is  a  file Requester.
  224. Fortunately  there  are  several of these available in the public
  225. domain.  There is FileReq by Peter da Silva on Fish Disk #85, amd
  226. Getfile  by  Charlie  Heath  on  Fish Disk #41. I have been using
  227. FileIO  by  RJ Mical from the prosuite package on Fish Disk #107.
  228. Prosuite  also  has  several  other  good  utilities.  There is a
  229. ColorWindow  for  editing  the  palette of any screen. There is a
  230. requester  handler  to help with more elegant requesters than the
  231. AutoRequest() requesters I use.  
  232.     Skel doesn't   begin   to   exercise   all  the  features  of
  233. Intuition,  but  it  provides  me  with a good starting point for
  234. getting  my application up and running quickly. It should also be
  235. a good way for a novice to learn Intuition a step at a time.  "z
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.