Ê




       	  									BrainHex
																					Hexadecimal File Editor for Macintosh
						  							 									  		           Version 1.0
                                                           January 15, 1996
                                                              Release Notes
                                                   Written by Brian "Brain" Fries
                                                ©1994-1996 BrainScan Software
                                                            All Rights Reserved
                                                        Shareware $25 ($19 hex)
                                                    E-mail: brainscn@psyber.com
                                                 http://www.psyber.com/~brainscn

Hey, dude, what it this thing?
BrainHex is the world's greatest (and noisiest) hexadecimal file editor for Macintosh. It allows you to view and edit the contents of either fork (data or resource) of any Macintosh file in hexadecimal code. If you don't know what hexadecimal is, you probably don't need this program. If you do, you will find this tool indispensible.

Features
× Open multiple data and resource forks simultaneously.
× Create new files or new forks for existing files.
× Search and Replace forward and backward through a fork.
× Insert or overwrite data entered in Hex or ASCII.
× Jump to specified address, optionally extracted from selected data.
× Drag and drop any document or group of documents to the BrainHex icon for easy opening.
× Custom font (Hexus, embedded in the Application) for viewing non-displayable ASCII characters.
× Full-featured Finder Info editing dialog.
× Edit values in ASCII, Hex, Signed and Unsigned Decimal, Octal, Binary, or Roman Numerals.
× Export Hex dumps as TEXT files.
× Printing Hex dumps.
× Extensive use of Balloon help.
× Launch open document to its creating application or an application of your choosing.
× Open and edit Alias files.
× Undo of latest document-altering operation.

BrainHex Package Contents
× BrainHex - the BrainHex application, version 1.0.
× BrainHex.ReadMe - this elegantly written release document.
× BrainHex.Help - provides more extensive descriptions of menu and dialog items.
× Test document - A document containing all ASCII values for you to play with.

Installation
× Put BrainHex wherever you want it.
× Drop a file you don't mind screwing up onto BrainHex and away you go.

Requirements
× BrainHex requires System 7.0 or later. If you're still using System 6, tough.
× BrainHex requires a 640x400 or larger monitor.
× BrainHex should work on any Mac that supports System 7.
	I haven't tried them all, but I've run it on a wide variety of machines, ranging from a PowerBook 100 to a PowerMac 9500. If it doesn't work on your machine, let me know.


General Usage
× ALWAYS EDIT A BACKUP OF THE FILE. This cannot be stressed enough. By inserting, deleting or changing values in the data or resource fork of a file, serious damage can be done. Feel free to experiment and play with the contents of files - that's the best way to learn about them - but ALWAYS EDIT A BACKUP OF THE FILE.


Interface
All menus and dialog elements have Balloon Help associated with them. Please refer to the balloon help for descriptions of individual items.

Major components of the user interface include the following:
× Menus
  BrainHex has four functional menus: File, Edit, Tools and Windows. File contains I/O related items (open, close, save, export, print..., launch). Edit contains the standard undo and clipboard stuff, plus a Preferences command. Tools contains BrainHex-specific functions, most of which are also available from the dashboard. Windows contains commands for navigating among windows currently open in BrainHex.

× Fork Windows
  The main editing windows in BrainHex are called Fork Windows. Each open data or resource fork is contained in its own Fork Window. A Fork Window is made up of several distinct regions: the Dashboard, the Address box, the Hex box and the ASCII box.

  The Dashboard contains several picture buttons and box buttons that generally provide alternative access to Tools menu commands. The buttons include:
  ¥ Unlock Fork (a Padlock, showing current locked or unlocked state). Toggle between Read-Only and Modifyable modes. If switching from Modifyable to Read-Only, the user will be prompted to save, cancel or discard changes.
  ¥ Find... (a magnifying glass with an ellipses). Display the Find/Replace Dialog (see below) to allow entry of a Find Value to search for. A Find may or may not actually be executed, depending upon the button used to exit the Find Dialog.
  ¥ Find Again (a magnifying glass by itself). Find the next occurrence of the current Find value. If the shift key is held down, the previous occurrence will be found instead of the next occurrence. The Find/Replace Dialog will be displayed if no find string is currently defined. Holding the Shift key while clicking this button causes a backward search.
  ¥ Replace (00 overwriting FF). Replace the current selection with the contents of the "Replace" data entered in the Find/Replace dialog.
  ¥ Replace & Find Again (Combined Replace and Find buttons). Replace current selection thend Find next occurrence of the Find data. Again, Shift makes the search go backward.
  ¥ Show All ASCII (a little F and a big F with or without a red circle and slash, representing the display of the character 0xFF when this mode is enabled). Toggle between display of generally non-displayable characters (represented by their Hex values in the Hexus font) and showing these characters as single dots. Note that enabling this mode automatically enables Show High ASCII mode as well, if it is not already on.
  ¥ Show High ASCII (the PI character (¹) with or without a red circle and slash). Toggle between display of characters in the ASCII range 0x80 thru 0xFF as high-ASCII characters or a periods. This is useful when looking through binary forks for readable text values. Note that this mode varies the results of double-clicking in the ASCII text box of a window. When in High ASCII mode, High ASCII characters will be considered part of a word to be selected. When not showing High ASCII characters, they will not be considered part of a word to be selected. Note that disabling this mode automatically disables Show All ASCII mode as well, if it is on.
  ¥ Insert Mode (the letter B squeezing between an A and a C, or replacing the C). Toggle between insert and overwrite typing modes. When in Insert Mode, the cursor will be a blinking vertical bar, and typing a character will be cause it to be inserted prior to the character to the right of the cursor, causing all following characters to be shifted one position to the right. When in Overwrite Mode, the cursor will be a box around the current character, and typing a character will cause it to replace the character in the box.
  ¥ Jump (a Kangaroo). Display the Jump To Dialog (see below) to allow entry of a destination address or offset, and a count of bytes to select at the new location. If the dialog is cancelled, the current cursor position and selection will remain unchanged. If the Jump is executed, the previous position and selection information will be saved for use with the Jump Back command. Clicking this button with the Shift key held down automatically executes the jump with its default values - the Jump To Dialog will not be displayed.
  ¥ Other Fork (a red trident). Clicking this button causes a BrainHex window with the "other" fork (data if editing resource, resource if editing data) to be displayed as the front window. If the other fork is not currently open, it will automatically be opened.
  ¥ File Info: (box displaying current EOF, file type and creator). Display a dialog allowing information about the file to be viewed and modified, including file type and creator, comment and various Finder flags.
  ¥ Selection Info: (box displaying current selection offset (in decimal and hex) and length). Same as the Jump button.
  ¥ Selected Value: (box containing current selection of 1-4 bytes as Decimal, Octal and Binary values). Display a dialog allowing editing of the current selection (1-4 bytes) in a variety of formats.

  The Address box displays the offset from the beginning of the fork to the beginning of each displayed line of data, either as a decimal or hexadecimal value, depending on the setting of the Decimal Addresses option in the Tools menu. Values in the Address box cannot be edited.

  The Hex box displays for editing 16 bytes of data per line in hexadecimal notation in 2-byte pairs.

  The ASCII box displays for editing 16 bytes of data per line in raw ASCII form, with optional display of high-ASCII and normally non-displayable characters.

× Find/Replace Dialog
  The Find/Replace Dialog is displayed in response to selecting the Find... item in the Tools menu, or clicking on the Find button on the dashboard. It allows you to enter a search string and a replace string, in either ASCII or Hex, and to execute find and replace operations.

× Jump To Dialog
  The Jump To Dialog is displayed in response to selection of the Jump To... item in the Tools menu, or clicking on the Jump button on the dashboard.

  The default values displayed in the Jump To Dialog when it is brought up are as follows:
  ¥ If the current selection is 4, 6 or 8 bytes long, the first four bytes will be used as the default Jump Value (if within the range of the file), and the following 2 or 4 bytes (if available) will be used as the default Selection Length.
  ¥ Failing that, if the Relative Jump To checkbox was set the last time the Jump To Dialog was executed, the dialog will default to the same values as the last time the Jump To Dialog was executed.
  ¥ Failing that, the dialog will default to the Jump Back values (the last location jumped from) for the front window (initially zero).

× Preferences Dialog
  The Preferences Dialog is displayed in response to selection of the Preferences... item in the Edit menu. This dialog allows the user to customize certain features of the BrainHex interface.

× Finder Info Dialog
  This dialog displays various information about the current file and allows you to rename a file, change its type and creator values, change its comment, change its color (label), and change a number of flags associated with the file. To avoid being overly verbose, I'll just describe the function of the four buttons at the bottom. If you can't figure out what to do with the rest of the dialog, you probably shouldn't do anything.
  ¥ Save. This button will immediately save any changes you have made in this dialog and close the dialog. Note that these changes are written out regardless of whether or not you save any changes to the fork being edited in the main BrainHex window.
  ¥ Cancel. This button will discard any changes you have made in this dialog, and close the dialog. The Finder Info associated with the file will remain unchanged from when you brought up the Finder Info dialog.
  ¥ Revert. This button will discard any changes you have made in this dialog, and will leave the dialog open for further editing. The Finder Info displayed after pressing this button will be identical to when the dialog was initially brought up.
  ¥ Set Like... This button will bring up a Standard Get File dialog, allowing you to locate a file whose Finder Info you would like to duplicate for the current file. If you cancel the Get File dialog, no changes will be made. If, however, you select a file, then all info displayed in the Finder Info dialog, except for the file name, will be set to the same values as the file you located. Also, if the selected file has no comment, any existing comment for the file being edited will not be deleted. After selecting a file or canceling the Get File dialog, you will be returned to the Finder Info dialog for further editing. No changes will be saved until you press the Save button.

× Edit Selection Dialog
  This dialog displays the current selection of 1-4 bytes in ASCII, Hex, Signed and Unsigned Decimal, Octal, Binary (1-2 bytes only) and Roman Numeral (values less than 10,000) representations, and allows editing in any of these representations if the fork is unlocked.

× Launcher Editor Dialog
  This dialog displays a list of currently configured custom launcher applications, and allows you to add new custom launchers and delete launchers from the list. Configured custom launchers show up in the Launch File To sub-menu of the File menu.

× Cursor Movement and Selection
  ¥ Mousing around.
    + A single click in the Hex or ASCII box of a BrainHex window will cancel any current selection and move the cursor to the byte clicked on.
    + A single click in the Hex or ASCII box of a BrainHex window with the Shift key held down will extend or shrink the current selectionto be from the current cursor position or beginning of the current selection to the byte clicked on.
    + A double-click in the hex box of a BrainHex window will cause any current selection to be canceled and the two-byte pair clicked on to be selected.
    + A double-click in the ascii box of a BrainHex window will cause any current selection to be canceled and the "word" clicked on to be selected. A word is defined as a run of displayable ASCII characters, not including spaces or control characters. If High ASCII mode is turned on, High ASCII characters will be considered part of a word.
    + A click and drag of the mouse starting inside the Hex or ASCII box of a BrainHex window will cause any current selection to be cancelled and a new selection to be established starting from the byte originally clicked on and extending to the byte the mouse was pointing to when the mouse button was released. If the mouse is dragged above or below the box clicked in, the document will automatically scroll until the mouse is moved back into the box or the button is released.

  ¥ Cursor keys.
    + The Home key scrolls to the top of the document and moves the cursor to the first byte in the document. If the Shift key is held down, the selection will be extended to the beginning of the document. If the Shift key is not held down, any current selection will be canceled.
    + The End key scrolls to the bottom of the document and moves the cursor to the last byte in the document. If the Shift key is held down, the selection will be extended to the end of the document. If the Shift key is not held down, any current selection will be canceled.
    + The Arrow keys move the cursor around one byte or line at a time, as appropriate. If the Shift key is held down, the selection will be extended or reduced. If the Shift key is not held down, any current selection will be canceled.
   + The left and right arrow keys combined with the Command key move the cursor to the beginning or end of the current line. 
    + If the Shift key is held down when any of the above cursor movement keys are used, the selection will be extended or reduced as appropriate. If the Shift key is not held down, any current selection will be canceled.
    + The Tab key switches the focus between the Hex and ASCII boxes of the current BrainHex window.


× Exporting Dump Files
BrainHex allows you to save a Hex dump as a TEXT file that can then be opened and perused using most any text editor or word processor, giving you the ability to use whatever tools such applications provide. The saved file is in essentially the same format as the Fork window from which it was created - address then hex values then ASCII values. The dump is saved with the same display options as the Fork window from which it was printed, with regard to hex vs. decimal addresses, and whether high-ASCII and control characters are shown as themselves or as simple dots. Two characters are exceptions to this rule: 0x0D (return) and  0xFF. These two characters can cause undesirable things to happen to dump files or prints, so they are always replaced with a simple dot character (BrainHex uses an option-space character (0xCA) for this).


× Printing Hex Dumps
BrainHex prints in the same format as the Exported dump files, again utilizing the display options from the Fork window that is printed. If text is selected, only those dump lines that contain selected text will be printed. If there is no selected text, the entire dump will be printed. The name of the Print menu item changes between "Print Selection..." and "Print..." to indicate whether part or all of the dump will be printed. Settings from the Page Setup... dialog are saved in the BrainHex Prefs file, so BrainHex will always default to the last options you set.
If you want to print control characters in the BrainHex character set, you must have Font Substitution turned off in the Page Setup dialog, and you must leave BrainHex running during printing, so that the system will download BrainHex' internal custom font (Hexus) to the printer.


Coming Attractions...
The following features may show in future releases of BrainHex, or may never actually be implemented at all. Anyway, here are some of my ideas. I'm accepting votes for your favorite unimplemented feature (write-in candidates are allowed) to help me adjust my priority schedule.

× Drag and Drop. All applications should support inter- and intra-application drag-and-drop where appropriate. Its a cool feature. BrainHex doesn't support it. I'm embarrassed.

× Hexadecimal Cut-and-Paste. Hold the option key down, and the clipboard could allow copying the selected data in its hex representation.

× Non-Modal Finder Info Dialog. The Finder Info dialog should be enhanced to be non-modal, to allow editing of info for volumes and folders, to allow editing of dates, and to optionally show dates as their integer values.

× Double-Click Drag. After double-clicking, if button is still down, user should be able to drag out the selection, and it should shrink or grow in whole-word increments.

× ASCII-Only display. It would sometimes be helpful to hide the Hex portion of the fork window and display only the ASCII portion, which could be enlarged to show more data per line.

× Multiple File Search. It would be way cool if BrainHex supported scanning multiple files, from a selected list or down a directory tree, for search strings.

× File Comparison. Another nifty feature would be to provide a side-by-side comparison of two files, highlighting the differences and allowing data to be easily copied back and forth.

× Patcher Applet Creation. Once file comparison is supported, it would be pretty simple to also provide a patcher application creation feature, like ResCompare does.

× Disk-based Editing. Currently BrainHex needs to load an entire file into memory for editing. It would be nice if BrainHex could work with very large files without requiring them to be read entirely into memory.

× Resource Fork Intellegence. BrainHex could be made smart about the structure of a resource fork, displaying the current resource being edited and maintaining resource fork integrity so that pointers and lengths could be updated properly when data is inserted or deleted. This would allow resource fork editing with improved likelyhood of having a valid resource fork when done.
 
× AppleScriptability. BrainHex could provide a very verbose and useful Apple Event suite, including the full text editing suite plus some events specific to BrainHex. This would create a powerful environment for batch manipulation (and decimation!) of files.

BrainHex History
× Version 1.0 - Developed between August 1994 and January 1996
  Why? Because long ago I used to use a program called FEdit to poke around in applications and documents, but that program ceased to work somewhere along the line, as I upgraded from a Mac IIci running System 6 to a Quadra 700 running System 7 to a PowerMac 8500 running System 7.5.  I don't know whether FEdit was ever upgraded to support the newer stuff, but I got by without it. Well, I started analyzing a potential new project at work, and found myself with a need to reverse engineer the document structure of a couple applications, and I thought a Hex editor would be quite useful. I poked around Internet FTP sites without finding anything to suit my needs, so I decided to utilize my voluminous free time to write my own Hex editor. A couple of weeks after I started, a friend found the fine program HexEdit, by Jim Bumgardner, on an online service and forwarded a copy to me, including source code. While this tool would suit my needs, I already had a working prototype of BrainHex, and I had a few ideas I wanted to try out in terms of interface and nifty little tools. Plus I wanted to get a publicly released product under my belt before moving on to more adventurous tasks.


BrainScan Software
  BrainScan Software is a major supplier of development tools, multimedia presentation products and educational software, with over 2,500 employees located in 37 countries, and over $3 billion in annual revenues.
  Oops... that must have slipped through the time portal...
  BrainScan Software is actually a relatively small startup firm, and BrainHex is its first product, though the members of the conglomerate have extensive experience creating products that make other people rich. However, 2 years from now, who knows?

  Feel welcome to contact BrainScan Software any time you wish. We appreciate comments regarding:
  ¥ how gloriously wonderful our software is
  ¥ great things you have accomplished with our software
  ¥ ShareWare fees
  ¥ suggestions for new features
  ¥ problems with our software
	¥ problems with our documentation
  ¥ the price of tea in China
  ¥ etc.

BrainScan Software can be reached via SnailMail at:
      BrainScan Software
      136 College Way
      Auburn, CA 95603

BrainScan Software can be reached via E-Mail at:
      brainscn@psyber.com

Visit BrainScan Software's Home Page on the Web at:
      http://www.psyber.com/~brainscn

Semi-Legal Stuff
× BrainHex is ShareWare. It is freely distributable, but is not freeware or in the public domain. You may use it to your hearts content for the first 30 days. After that, if you like it and find it useful, please fill out the registration form (accessible from the About BrainHex dialog), print it out, and send it with a check for $25 US ($19 Hex) made out to BrainScan Software at the above address, and you will be added to our database of happy campers.

Once BrainScan Software has received your registration, you will receive a registration code that will kill that irritating "register me" dialog that pops up occasionally when you launch BrainHex.

× BrainHex is NOT guaranteed. BrainScan Software takes NO RESPONSIBILITY for any damage this program may cause to your system or data due to either defect or misuse. While we strive to create solid, bug-free software, this is not a perfect world and those little critters are sure to sneak in somewhere. If you alert us to a bug, we will make every effort to fix it quickly and get you a new version (if you are registered).

× BrainHex CAN DAMAGE FILES. Resource forks, and the Data forks of many types of documents, contain pointers and lengths referencing the information in the files. By modifying a fork directly, particularly by inserting or deleting data, or modifying an address or length value, the file may be rendered unusable. This is not the fault of BrainHex. Be sure you either know what you are doing, or you are messing with a file you won't mind losing.

× Freely Distributable. As with most ShareWare, you may feel free to pass the BrainHex package along to friends and family, post it on online services, or package it with other publicly distributable software on disk or CD-ROM. A few guidelines to follow:
  ¥ Always include the entire BrainHex package, including the latest version of the BrainHex application, this ReadMe document, the Help document and the sample document.
  ¥ You may not charge a fee for this software, though you are entitled to media and handling fees if so desired.
  ¥ Let BrainScan Software know where and how this product has been distributed, preferably via the E-Mail address listed above.
	¥ If you include BrainHex on a CD-ROM, you must send a free copy to BrainScan Software.

× BrainHex is ©1994-1996 BrainScan  Software, All Rights Reserved.

How To Register:
In the About BrainHex dialog, you will find a button labeled "Register". If this button is not available, the dialog probably says "Registered to Joe Schmoe" or someone closely related to him at the top. In this case, hold the shift key down when selecting the About BrainHexÉ menu item to reveal the "Register" button.

Press the Register button to bring up the registration dialog. Here you can enter your user ID and registration code, then press Register to register your copy of BrainHex, thus hiding the Register button in the About dialog.

To obtain a registration code, press the Edit Form button in the registration dialog to bring up the Registration Form dialog. Fill in the blanks and press the Print button to print out this form. If you cannot or do not wish to print the form, you may hand write the form, including all the information requested in the Registration Form dialog.

Finally, send your registration form, along with a check for your $25 US ($19 Hex) shareware fee made out to BrainScan Software, to the following address:

      BrainScan Software
      136 College Way
      Auburn, CA  95603
      USA

Special Thanks...
to my alpha and beta testers, who provided many great ideas and found a multitude of bugs in BrainHex (and you thought it was perfect from the beginning!): Bob "Guru" Studer, Craig "Boss" Hassig and Stan "Scan" Stoneking.

Important Footnote:
What? You're still reading? Hey, the document is over. Go home, or get back to work, or whatever you should be doing. Certainly you can find something better to do than wasting away your day reading "Read Me" documents.

Live long and prosper. So long, and thanks for all the fish. Thanks for your support. Visualize whirled peas. Eat at Joe's. Don't forget to wash behind your ears. We'll leave the light on for you. I'm Chevy Chase, and you're not. What are we gonna do today, Brain? Cool, they got a blimp! It's morphin' time! I'm not dead yet. Laugh while you can, monkey boy. Never go in against a Sicilian when death is on the line. I am completely operational, and all my circuits are functioning perfectly. Would you like to play a game? And now for something completely different. I'm so glad you're not a dinosaur! That's all, folks!


	Ê




