CICA 1993 August/CICA.cdr/unzipped/programr/blrplt/blrplate.doc

Text File | 1992-04-12 | 10.8 KB | 331 lines

                                                     April 12, 1992

                                   BoilerPlate

                 A boiler plate code generator for ObjectWindows
                                   Version 1.0


        OVERVIEW

        After writing several OWL programs,  it seemed like each time I
        started a new one, I was typing the same boiler plate code over
        again each time.  I decided that redundant stuff like this really
        ought to be handled by a program.  BoilerPlate is the result.

        Briefly, here's how it works:

          After spending some time deciding what you want in the program,
          use WRT or Resource Workshop to build a resource (.RES) file.
          It should contain your menu, icons, cursors, accelerator, and
          in the case of a TDlgWindow descendent, the dialogbox and
          controls for the main window.  The identifiers you use should
          be put in an include file for later use.

          Start BoilerPlate and read in the .RES and .INC files.  You
          then make choices for various things like program name, what
          window messages you want to handle, what OWL methods you'll be
          overriding, etc.

          BoilerPlate then writes out the source defining your main
          window object and including empty (mostly) methods for the
          menu items and window messages you selected.  The source can be
          compiled and run.  It won't do much, but you can select menu
          items, etc.

          Now all you have to do is the fun part--fill in the empty
          routines.

        Here's a summary of the code BoilerPlate generates:

          -The object type declaration for both the application and main
           window.  The main window may be a descendent of TWindow or
           TDlgWindow.  The type declaration has method headings for all
           the methods listed below.

          -Your choice of names for the application, main window,
           program, class name, and window caption.

          -Skeleton response methods for:

             *constructor, destructor, SetupWindow, GetClassName,
              GetWindowClass.


                                   1











             *All menu items.
             *Your choice of Window messages (wm_xxxx messages).
             *OWL methods you wish to override.

          -Statements for:

             *Loading your choice of icon, cursor, accelerator, and menu.
             *Loading the .RES and .INC file.
             *Your window style (ws_xxxx) and class style (cs_xxxx)
              selections.

          -For TDlgWindow descendents:

             *Pointers defined for dialogbox controls.
             *Appropriate InitResource calls for controls.
             *Response methods for control notification messages.


        Here it is in more detail:


        Resource File Considerations

        BoilerPlate can make use of the menu and menuitems, icons,
        accelerators, cursors, and main window dialogbox and its controls
        (TDlgWindow) in the .RES file.  It's OK to include any number of
        other resources, though.  If you don't feel like designing a
        fancy icon or cursor at this stage, do something simple--Boiler
        plate really only needs the identifier.

        While BoilerPlate can work without any symbols, you're not
        likely to be pleased with code that's full of routines like
        '_204'.  It's most important that identifiers be provided for
        menuitems and dialogbox controls.  On the other hand, for a
        single accelerator, icon, or cursor, assigning an identifier
        isn't all that necessary.

        In some cases, BoilerPlate will slightly change your identifier
        to form a related identifier.  Here's the way it's done:

          Any underscores will be stripped from the symbol.  So, for
          instance, if you assign 'cm_Write' to a menu item, you'll end
          up a procedure 'cmWrite' to handle that menu command.

          If the identifier contains no underscores, one will be added as
          the first character so that 'cmOpen' will become '_cmOpen'.

          Finally, if no identifier is provided, the numerical value
          found in the .RES file will be used with an underscore for the
          first character.




                                   2











        Windows allows the same numerical ID to be reassigned in
        different resources so that you could have an icon, menuitem,
        and cursor all with an ID of 100, as:

          MyIcon = 100;
          MyCursor = 100;
          cm_Open = 100;

        But such duplicates pose a problem for BoilerPlate, since it has
        to match the numbers it finds in the .RES file with Identifiers.
        When BoilerPlate finds two or more possibilities for a match, it
        throws up a dialogbox listing the names and where it needs the
        symbol (menuitem, icon, etc) and lets the user choose.  For a
        large resource file with many duplicates this could become
        somewhat of a hassle so you might want to adopt one or more of
        the following strategies when designing your resources:

          Try to assign a different number sequence to each resource.

          Use string identifiers for menu, icon, cursor, and dialogboxes.
          There is no ambiguity with string identifiers.

          Pare down the .INC file to include only those identifiers that
          will be used by BoilerPlate.

        Once you've got the resource and include file, you're ready to
        run BoilerPlate and load the two files.  (Use 'Open' and 'Load
        symbols' in the File menu.)  Once the files are loaded, there are
        a number of dialogboxes to 'visit' where you can make various
        choices.  As you OK each dialog, its location on the menu gets
        checked and after all are checked, you then write the source
        code.

        The dialogs are described somewhat briefly below.  However, each
        dialogbox has a Help button which will bring up additional
        information.


        Names Dialog

        In the Names dialog, you choose your program name, main window
        name, application name, class name, and main window caption.
        In the case of window and application names, BoilerPlate will
        add a preceding 'T'.  Hence if you choose 'MyWindow' for a window
        name, it will appear in the program as TMyWindow and have a
        pointer name of PMyWindow.

        In this dialog, you also choose whether your main window will be
        a descendent of TWindow or TDlgWindow.





                                   3











        Styles/Window Styles  (TWindow only)

        Here you choose the ws_xxxx window styles.  The selection
        possibilities are shown in the left listbox and the choices in the
        right listbox.  To add a ws_ style, select it and push the 'Add'
        button (or double click on the selection).  Removing a selection
        from the right listbox is done in a similar manner using the
        'Delete' button.

        Note that ws_OverlappedWindow is a combination of a number of
        other selections which will appear individually in the right
        listbox.  The 'Result' window shows the selections reorganized as
        they will be inserted in the source.


        Styles/Class Styles

        The choice of cs_xxxx styles are made here in a similar manner.


        Resources/Menu Accelerator

        If there is more than one menu or accelerator in your resource
        file, you can make the choice for the main window here.


        Resources/Icon Cursor

        Here you can choose from among the cursors and icons defined
        within your resource file as well as windows standard icons and
        cursors.  You can also type in an identifier for an icon/cursor
        to be designed later.


        Methods/Window Messages

        The listbox on the left contains possible window wm_xxxx messages
        from which you can select to handle within your program.  Only
        the more common messages are listed but you can type in any other
        messages if necessary.


        Methods/Other Methods

        Here you can select from a list of standard OWL procedures which
        you may need to override.  You can also enter other special
        methods you may need.  When entering your own methods, you should
        include the parameter list if applicable.


        Once you've made all the necessary selections, you then choose
        'Write source' from the File menu to output the Pascal source


                                   4











        code.  Barring a few things that can go wrong like selecting a
        conflicting symbol, the code should compile and run.


        TDlgWindow Descendants--Special Considerations.

        If your main window is going to contain dialogbox controls such
        as edit boxes, listboxes, buttons, you should consider making it
        a descendent of TDlgWindow rather that TWindow.  It's a lot
        easier to lay out controls in the resource editor than it is to
        guess at positions and sizes.  You save some coding too.

        Here's a couple of points regarding TDlgWindow descendents:

          When you design your main window dialog, make sure you give it
          a class name.  Enter the same class name in the BoilerPlate's
          Names dialog.  (Actually, BoilerPlate will pick up the name
          when you select the main window dialog.)

          A menu is optional.  The menu is designed in the usual way, but
          its identifier is assigned to the dialog in the dialogbox
          editor.



        COPYRIGHT

                (C) Copyright 1992 by L. David Baldwin.
                          All Rights Reserved

        BoilerPlate may be copied and distributed freely providing that
        no fee is charged and it is not part of a package for which a
        charge is made.

        Source code for BoilerPlate is available for $20 (need not be
        sent in advance).  Also please report any problems, suggestions,
        etc.

        Contact me by Compuserve (the best way) or at one of the
        addresses below.

        Dave Baldwin
        CompuServe ID #76327,53.

             22 Fox Den Rd., (Summer)     144 13th St. East,  (Winter)
             Hollis, NH 03049             Tierra Verde, FL 33715
             [phone]               [phone]







                                   5