




                                    LLRE


                           Low-Level Resource Editor
                                 Version 1.1

                                     by
                                Jason Coleman

This program is shareware.  To legally use it after a 10-day trial, send the shareware fee of $25 to:
     Jason Coleman
     P.O. Box 179
     Callahan, FL 32011

Please direct questions regarding LLRE to me at (preferably) my GEnie mailbox, J.COLEMAN13 or to the address above.

Please help support the low-cost distribution of shareware with your $25 payment.




                          Introduction to LLRE
     LLRE is a program designed to compensate for shortcomings of various Apple IIGS resource editors.  LLRE is designed to act as a supplement to resource editors available today.  Although LLRE is capable of creating and editing any type of resource, it would be rather tedious to create all of your resources with LLRE.  This is because LLRE is not a macro or graphic resource editor like TML Pascal II or Genesys.  All resource editing is done either using either hexadecimal numbers or character strings.  Given, this can be cumbersome, but it offers flexability.  Any kind of resource can be edited with LLRE, not just a few types.  This allows the user to edit all predefined resource types, as well as any custom ones.
    LLRE has much more than actual resource editing in its favor, however.  LLRE can perform numerous manipulations of resources, their files, and their forks.  Perhaps the most useful of these manipulations is the ability of LLRE to help repair a damaged resource file.  Some of the most frustrating "programming" of my life came when trying to repair a damaged resource file.  Damaged resource maps can lead to disaster.  Several times I had to create an entirely new resource file.  A utility under the Copy menu in LLRE (Copy resources one-by-one) helps salvage as much of a damaged resource file as possible.  This is done by copying each resource in the file one by one into another file.  This way, in the new file, a new, correct, resource map is created by the Resource Manager.  Then, the new file can usually be easily fixed with the resource editor.  

                           LLRE Features
Here are some of the features of LLRE (they will be explained in detail below).
-  Edit any type of resource, not just a few major types
-  Edit resources as character strings or hexadecimal numbers
-  Automatically edit standard text and string types
-  Sophisticated user interface
-  Help repair resource files which have become damaged or jumbled
-  Import a data fork of a file as a resource
-  Export a resource to a data fork
-  Easily edit attributes of a resource
-  Create new resource files
-  Give a non-extended file a resource fork
-  Clear the resource or data fork of a file
-  Copy the resource or data fork of a file
-  Cut, Copy and Paste resources from one file to another
-  Delete resources from a file
-  Add (combine) resources of one file to the resources of another file

                      Resource Editing With LLRE
     This section explains how to use the major feature of LLRE:  the resourceeditor.  Other features are available as menu options and are described below.
Opening a resource file-  To open a resource file for editing, select the Open item under the File menu.  Select the file you wish to edit.  Upon opening of this file, a window will appear on the desktop with the title of the file you just opened.  Inside the window will be two lists and four buttons.  
     Resource file information-  Clicking on the Info... button in a file window brings up a dialog box displaying the number of resources, number of resource types, and size of the resource fork represented by the window.
Selecting Resources-  The first list (on the left) is the list of resource types present in the file.  The second list is the list of all resource IDs of the currently selected type (note that when the window is first opened this list will be empty because no type is selected).  To select a resource, first click on the type of the item in the first list, and then the ID of the item in the second list.  Note that multiple resource IDs can be selected at once (all must be of the same type) by holding down the Apple key while selecting.
    Editing Resources-  Two types of resource editing are currently supported in LLRE, string and hexadecimal.  In other words, each resource can be edited in two ways, as each byte in the resource representing either an ascii character or a hexadecimal byte.  Standard text types are automatically edited with LLRE 1.1.  These types include Pascal and C strings, and TextBox2 and TextBlock types.  Non-text types are automatically edited as a hexadecimal stream.  After selecting the desired resource(s) to edit, click on the Edit Resource button (or double-click the resource ID).  To edit a resource in the non-standard way (for example, to edit a Pascal string as a hexadecimal stream), click Inverse Edit instead (or hold down the option key while double-clicking the resource ID). An edit window will appear.
     Creating New Resources-  A completely new resource of any type and ID can be created by clicking the New... button in a file's window.  A dialog box will appear asking for the resource type and ID of the new resource.  As defaults for the type and ID, LLRE supplies the currently selected type and an unused resource ID.  After selecting the type and ID, click the New Resource button to edit the new resource.  To edit the resource in the non-standard way, hold down the Option key while clicking the New Resource button.


    Edit Windows-  After selecting resource(s) to edit, edit window(s) will appear.  The title of each window will be the type and ID of the resource, and the information bar in the window will display the name of the file the resource is from and which type of editing is being done.  
The main part of the edit window is the large Text Edit box.  This is where the editing is done.  The resource will be displayed here either as a text string (with each character representing one byte in the resource) or as a string of hexadecimal bytes separated by spaces (Note that there are NO carriage returns in the hex stream.  LLRE expects only spaces between each byte).  If the editing is done as hexadecimal, LLRE will supply guidelines on the top and left sides of the text box to indicate which byte is currently being edited.  
     Four buttons also exist at the bottom of the window.  From left to right, the buttons are:  Import...-- this allows the user to import the data fork of a file into a resource.  Export...-- allows the user to export the data in the resource to the data fork of a file.  Attributes...-- Displays a dialog box enabling the user to edit the attributes of the resource with check boxes and radio buttons.  Save Changes--   Clicking on this button will cause changes you made to the resource to be saved back to disk.  If you make an error, simply close the window and don't click this button.   Note that standard text editing operations can be conducted in these windows using items in the Edit menu.


                             Other Features
       Following is an explanation of all pull-down menu items in LLRE.

The Apple Menu-  This menu contains the About LLRE item and any desk accessories you may have installed.  The About... item gives a copyright and shareware notice and allows the user to print a shareware envelope to a printer in slot 1.  

The File Menu-  This menu contains items which affect resource files.  The items are:
   Open...-  Allows the user to select a resource file to be opened for editing.  Once a file is selected, a window is opened bearing the name of this file.  Inside the window are lists of the resource types and IDs in the file.  See the section on resource editing for more information.
   Close-  Closes the currently active window on the desktop, whether file, resource, or desk accessory.
   Create Resource file... - Allows the user to select a filename and creates a new, empty resource file of that name.
   Create Resource Fork...- Allows the user to select an already existing filewhich is not extended (it doesn't yet have a resource fork) and creates a resource fork for this file.
   Clear Data Fork...-  Clear the data fork of a file selected by the user.  This call works on both extended and non-extended files.
   Clear Resource Fork...-  Clear the resource fork of a file selected by the user.  This call works only on extended files.
   Quit- Quits LLRE.

The Edit Menu-  The Edit menu serves several purposes under LLRE, according to what kind of window is currently active.  LLRE uses two 'clipboards', the public one (for text transfers) and a private one (for resources).  Resources are cut, copied, and pasted using this private clipboard.  Plain text in editing windows can also be edited.  These windows can share information with NDAs.  Below is a table illustrating the editing functions according to which type of window is open:

   Item    File Window                          Resource Window
----------------------------------------------------------------------------
   Undo    Not Supported                        Not Supported
   Cut     Copy selected resource(s) to the     Copy selected text to the
           private clipboard and remove         public (text) clipboard and
           them from the source file.           remove it from the resource.
   Copy    Copy selected resource(s) to         Copy selected text to the
           the private clipboard.               public (text) clipboard.
   Paste   Copy resource(s) on the              Copy text on the public
           private clipboard into the           clipboard into the active
           file of the active window.           resource window.
   Clear   Remove selected resource(s)          Remove selected text from
           from the file of the active          the active resource window.
           window.

The Copy Menu-  The copy menu contains items related to copying the forks of files.  
     Copy Data Fork...-  This item copies the data fork from one file you select to replace the data fork of another file you select.
     Copy Resource Fork...-  This item copies the resource fork from one file you select to replace the resource fork of another file you select.  The fork is read and written as one chunk of data, just like a data fork.  This is the fastest method to copy the resource fork.
     Copy Resources One-by-One...-  This item is to be chiefly used to repair resource files.  This method is a good deal slower than the previous method.  The advantage of this method is that it can help repair a damaged or jumbled resource fork.  This item copies the resource fork from one file you select to replace the resource fork of another (destination) file you select.  The resources in the file are read and written one by one.  Resources already in the destination file are erased.  If the resources in a file you are using become corrupted, run this copy.  This will create a new, uncorrupted resource map in the destination file.  The file should be then easily fixable.
     Add resources One-by-One...-  This item copies the resources from one file you select into another (destination) file.  The resources are combined into the destination file.  Resources already in the destination file are not removed.

                         Resource Editing Hints and Tips
I have found LLRE to be extremely useful to me as a programmer (I used early versions of LLRE to help me write this version).  Here are some tips and shortcuts you might find helpful in your resource programming:

-  Using Icons:  Create an icon with an icon editor and then import it into an rIcon resource ($8001).  This method can also be used to supply a custom icon for an Alert String ($8015).
-  Custom resource types:  Create a custom resource with an assembler or by other means and import it into a resource.
-  Supplying color tables for your windows and controls:  Create the tables with LLRE, and then edit the resource template to refer to these resources.
-  Resources requiring converters:  IMPORTANT:  LLRE does not use resource converters (LLRE has no way to tell how to convert a resource).  Consequently, the only way to edit these resources is unconverted.  So, be VERY sure you know what you are doing when editing a resource requiring a converter.  Code resources can be easily created with LLRE, however, even though they require converters.  Create a code resource by first linking the code as a generic load file and then importing it into a code (or CDev code) resource.  (Look for a demonstration soon on creating CDevs with LLRE). 
-  Supplying key equivalents under TML Pascal II:  TML Pascal II doesn't handle key equivalents for controls correctly.  Edit the control template with LLRE to easily fix this problem.
-  Eliminating recompilation:  Instead of recompiling a program after making modifications to its resource file, simply copy the resource fork of its resource file into the resource fork of the program.
-  Easily edit file attributes with the check boxes and radio buttons


                             In Conclusion
I have made every attempt to make LLRE as complete and error-free as possible.  If you have any complaints, suggestions, or recurring errors, please contact me.  Also, thank you for participating in the shareware distribution system.  Please copy this program and upload it and give it to everyone you know who is interested. 


Apple IIgs is a registered trademark of Apple Computer, Inc.
TML Pascal II is a trademark of TML Systems, Inc.
Genesys is a trademark of SSSI, Inc.

