## Win32 Tutorial ..binding resource data files

Since win32lib now includes some excellent documentation in HTML format, ( in the complete package ) I've decided to eliminate my version, which was in this file. David has kindly allowed me to include his resource file generator programs for Lesson 19,
( in the \Demos\Bin folder. )
.. so this is some of the original documentation for it !

Two Notes:
Makeres.ex converts all 'included' file names to lower case, so any calls in your program to these files should also be in lower case.
If you change the name of your .exw after running makeres.ex, you'll have to match it with the same change to the .res file name.

    +-----------------------------------------------------------------------+
    ¦ RES - Resource Files for Euphoria                        version 1.1  ¦
    ¦     (c) 1998 David Cuny                                               ¦
    ¦     November 12, 1999                                                 ¦
    ¦     Internet:  dcuny@lanset.com                                       ¦
    +-----------------------------------------------------------------------+

      RES allows you to compact the read-only files you would send with a
      Euphoria application into a single resource file. You have three
      different options of how to include your data:

         1. Bundle the resource file onto your application file (.exe),
            and ship a single EXE file to your users.

         2. Bundle all the data files into one single resource (.res) file
            and ship a single additional file with your application; or

         3. Include all the data files with your application, as you do now.

      RES automatically detects which option you have selected, without
      your having to change code for any of them.

    +-----------------------+
    ¦ Standard Disclaimer   ¦
    +-----------------------+

      This program is distributed in the hope that it will be useful, but
      WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
      or FITNESS FOR A PARTICULAR PURPOSE.

      I do not accept responsibility for any effects, adverse or otherwise,
      that this code may have on you, your computer, your sanity, your dog,
      and anything else that you can think of. Use it at your own risk.

    +--------------------+
    ¦ How Does It Work?  ¦
    +--------------------+

      1. Include RES.E
      --------------------------------------------------------------------
      You must include the file RES.E before attempting to open any resources.
      RES.E attempts to determine where the resources are located:

            1. First, it checks to see if there is a RES file attached to the
               file that is running.

            2. If that fails, it looks in the local directory for a file with
               the same name as the executing file, but an extension of ".RES".
               If finds one, it uses that file as the resource file.

            3. Finally, it assumes that there is no resource file, and attempts
               to read the files as it normally would.

      2. Use the Approprite RES Routines
      -----------------------------------

       Res only adds a handful of routines. They are detailed in the following
       section. For anything else, just use the built-in Euphoria file routines.

            Function            Replaces
            -----------------------------
            rOpen()             open()
            rEOF()              checking get/gets return codes
            rSeek()             seek()
            rWhere()            where()
            rReadBmp()          read_bitmap()
            rFile()             n/a

      Reference Your Resources
      -------------------------
      In order to know that a resource is to be included in a file, you need
      to name it either as a literal in one of the following routines:

            - rOpen
            - rFile
            - rReadBmp

      For example:

            rOpen( "data.txt" )     -- this will be included

      If you reference the file name using a variable, such as:

            rOpen( fName )          -- what is the file name?

       Res cannot determine the name of the file to include. To get around
       this, any file that you want included in the resource file that is
       not explicitly referenced in rOpen needs to defined with the procedure
       rFile:

            rFile( "moredata.txt" )  -- this will be included

    +-----------+
    ¦ Routines  ¦
    +-----------+

        rOpen - Open a Resource
        -------------------------
        This acts pretty much the same as the open() function, returning a file
        handle:

            rOpen( ,  )

        It does a little additional housekeeping, and points to the correct
        offset into the resource file.

        rEOF - Check for End of Resource File
        --------------------------------------
        This returns true when the end of resource has been reached. It should
        be used before each read:

            rEOF(  )

        rSeek - Position in a Resource
        -------------------------------
        This is the same as a "normal" seek, but allows you to access a relative
        position in the resource file:

            rSeek( ,  )

        rWhere - Return Position in a Resource
        ---------------------------------------
        This is the same as a "normal" where, but returns the relative position
        in the file. It is meant to be used with rSeek:

            rWhere(  )

        rReadBmp - Read a Bitmap File
        ------------------------------
        This is a rewrite of Euphoria's read_bitmap() routine, altered so that
        it works with resource files.

            rReadBmp(  )

        rFile - Include a Resource
        ---------------------------
        Files that are mentioned explicitly by name in an rOpen statement are
        automatically added to the resource file. You can also include a file
        in the resource file with:

            rFile(  )

    +---------+
    ¦ Example ¦
    +---------+

      This example is a simple read file example:

        -- demo.ex
        -- demonstrate resource files

        include res.e       -- required

        integer handle
        object data

        -- open the resource
        handle = rOpen( "data.txt", "r" )

        if handle = -1 then
            puts( 1, "Unable to open file.\n" )
            abort(0)
        end if

        -- read the resource
        while not rEOF( handle ) do

            -- read from the resource
            data = gets( handle )

            -- echo on screen
            puts( 1, data )

        end while

        -- close resource
        close( handle )

    +--------------------------+
    ¦ Creating A Resource File ¦
    +--------------------------+

      You can create a resource file with the program MAKERES:

        ex makeres

      The resource file that is created will be given the same name as the
      .EX file, but with a .RES extention.

      MAKERES will include files into the resource file if they are mentioned
      in an:

            1. rOpen() function,
            2. rFile() statement, or
            3. rReadBmp() funtion

      Example; Creating Resource File
      ---------------------------------
      To create a resource file for the demo program, enter:

        ex makeres demo.ex

      The resource file DEMO.RES will be created. You can delete the data file
      DATA.TXT and the demo will still run.

    +-------------------------------------+
    ¦ Attaching A Resource File To An EXE ¦
    +-------------------------------------+

      You can combine a resource file with a Euphoria EXE with bindres:

        ex bindres

      Before you run this, you will need to bind the .EX file, and build a .RES
      file.

      Example: Binding A Resource File
      ---------------------------------
      Again, I will use the demo program as an example. First, create a resource
      file for the demo program by typing:

        ex makeres demo.ex

      and the file DEMO.RES will be created. Next, create an executable version
      of the demo program by typing:

        bind demo.ex

      This will create the file DEMO.EXE. Note that binding is only available in
      the registered version of Euphoria.

      Now, attach the resource file to the executable by typing:

        ex bindres demo.exe

      This concatonates the resource file DEMO.RES to DEMO.EXE. You can now
      run the program without the data file DATA.TXT or DEMO.RES.

    +------------------+
    ¦ Release History  ¦
    +------------------+

        11-12-99    Release 1.1. Added rReadBmp routine.

        3-8-99      v 1.0a
                    Fixed file calculation error. Thanks to Neil Rigby!
                    Added some more examples

        6-12-98     Release 1.0

CONTENTS