NBASMIDE: Getting Started, General Help, and Tips and Tricks.

For version 00.23.80 or higher.

1.  System Requirements.
    A. You must have at least Windows XP.  This will not run on the Win9x family of Windows.
       Works fine on Windows 8, though I hate Windows 8, so I won't say much more than that :-)
    B. Not a whole lot of memory is required, unless you open many large source files at once.
    C. The NBASMW.EXE assembler.  See later how to point NBASMIDE to it. NBASMW can be freely downloaded at https://www.fysnet.net/newbasic.htm
    D. If you plan to use the NBASM library and example programs, you will need to download them
       also from the same page.
    E. Remember where you unzipped the NBASM.ZIP file above.
2.  Getting Started.
    A. You should have downloaded the nbasmide.zip file from https://www.fysnet.net/newbasic.htm
    B. Create a new directory and unzip the nbasmide.zip file to this directory.
    C. You should now have the following files:
       1.  NBASMIDE.EXE   The WindowsXP executable
       2.  NBASMIDE.HLT   The help file (see later for more about this file)
       3.  README.TXT     A small text file with information on where to get updates, etc.
    D  NBASMIDE requires the Windows version of .EXE from the NBASM package, called NBASMW.EXE.
    E. When you execute NBASMIDE for the first time, you will see a dialog box stating so.
       See Figure 1 below.



    E. Read the text, and if you accept, click on "accept".  This simply states that you know that
       NBASMIDE is in beta form, meaning it has not got all the bugs and quirks worked out, and that
       you know that you will use it at your own risk, knowing that, though unintentional, it may
       damage your system.
    F. Now you should see an empty workspace.  Figure 2 below has been resized 50% smaller to fit this
       screen.  
       1. If you have ran NBASMIDE before and have set the "Start with empty template" flag, you
          will see figure 2 below with an pre-created empty .asm file ready for use.
       2. If you have ran NBASMIDE before and have set "Load last WS on startup" flag, all files that
          were previously open in the previously opened workspace, before you exited the IDE, will be
          opened and the cursor for each will be in the same place as when it was closed.
       3. The tool bars may not be in the same place as the image below, however, you may move them
          as you'd like.  NBASMIDE will save their positions on exit so that they will remain as you
          place them.



    G. The 5 toolbars:
       1. The tree toolbar on the left will display the current files open.  Simply double click on
          any of the files listed and the IDE will open or bring to front that file.  Right click in
          the toolbar will allow you to hide the toolbar.
       2. The bottom window/toolbar is the view tool bar.  When you use the advanced find function, 
          the IDE will display the files found in this window.  You can hide or show this window via
          the view menu or simply pressing ESC while the main window has focus will toggle the view.
          When you assemble a project/file, the assemblers STDOUT will be displayed here too.  This
          way, you can double click on an error line and the IDE will move to that line.
       3. The three toolbars on the top, at first install, will be one on top of the other.  You may
          move them so that they are all on the same line.
          a. The first toolbar is the standard, open/close/undo, etc. toolbar.  It also contains the
             syntax check/build/execute/build window buttons.
          b. The second toolbar is the find toolbar.
          c. The third toobar is the insert toolbar.  Insert a text file, a binary file, a comment,
             or a signature of some kind.        
    H. NBASMIDE has now created a set of keys in your registry under 
             HKEY_CURRENT_USER -> Software\Forever Young Software\nbasmide.
       This is to store the toolbar positions, last workspaces, editor colors, make settings, and other 
       like settings.  You can set a flag in NBASMIDE to delete the registry entrys on the next time you
       exit.  At any time, as long as NBASMIDE is not currently running, you can use REGEDIT and go to that
       registry key to delete the whole key or any of the sub keys.  NBASMIDE will load just fine without
       them, though it will create new ones each time.

3.  Creating/Opening a new file.
    A. To create a new file to insert into the current frame work, click on the  button or use the File menu.
       This will bring a new dialog window asking for a type. (See figure 3) Choose a 
       type of file to create, or press Cancel to return to the mainframe.of file to create.  See tip #1 in
       the tips section.



    B. To open an existing file, click on the  button or use the File menu.
       You can open .asm files, .inc files, and other text files.  Only .asm and .inc files will be syntax colored
       if formatting is turned on.
    C. You may also open a recent file using the Recent Files item in the File menu.  NBASIDE will store the
       last 16 opened files.
    D. To save a file, use the  button and to save all opened files, use the  button.

4.  Setting the editor properties.
    A. Using the View menu, click on Editor Properties.  See Figure 4.



       1. Using the Colors tab, you can change the color of a given type of text, when the formatting flag is
          set.  See below.  To select a common color, click on the Forground drop down list.  If you want to
          use a custom color, click on "custom color" at the end of the list.  The Color Picker will show.
          Choose a color.
       2. Click on the Attributes tab (See figure 5)to turn on or off the formatting.  When on, the IDE will
          color format your source code.  When off, it will be simply black text.
       3. Also turn on or off the "Use Case Insensitive" check box.  If this box is checked, all source 
          instructions, directives, etc. must be in lowercase for the editor to format them with a color.  If
          you choose to use uppercase letters, make sure this is unchecked.
       4. The "Allow Member Popup Windows" check box, when checked, will display members of structures when
          you use the STRUCT. or STRUCT-> operators with in your code.
       5. The "Hide Build Window" check box, when checked, will not display the build window automatically.



       6. The Documents tab (See figure 6) allows you to load the last open workspace when you start NBASMIDE.
          When this is checked, each time you start the IDE, if a workspace was opened when you closed the 
          IDE last, the IDE will open all files that were previously open.
       7. Load Empty Template will create a new .asm document at startup, that already has the most used 
          directives and other operands ready for use.
       8. You must select one or the other or neither.  You can not have both checked at the same time.



    B. Setting the tab spacing for this document.
       1. While the main window has the focus, press Alt-Enter or use the View menu item and click on
          Properties.  This will display a dialog (See figure 7) which will allow you to set/change the tab
          spacing for this document.



       2. Checking the "Tabs to Spaces" check box will convert all tabs to spaces when that Tab key is pressed.
          (Use the Edit->Untabify and Edit->Tabify Selection menu options to convert a selected text from spaces
           to tabs and tabs to spaces.)
       3. Other useful information is also in the dialog.

5.  Assembling/Building a file or project.
    A. If you haven't already, you will need to modify the Settings, using the Make Settings item
       under the Make menu.  See figure 8.



       1. You must include the filename of the assembler in the Assembler field.  For example,
             D:\NBASM\NBASMW.EXE
       2. You must include the filename of the disassembler in the Disassembler field.
       3. The other fields only require the path to their respected items.
       4. This is where you point these fields to the directory you unzipped NBASM.ZIP above.
       5. Check the "Create Listing" check box if you would like NBASM to create a listing file
          at assembly time.  (Note: if this check box is clear and you want a one time listing file,
          hold down the left Ctrl key when clicking on the assemble tool bar button)
    B. Once you have created your file, or you have opened an existing assembly source file ready for
       assembling, you can click on the  button.  This will
       call NBASM with the /S parameter to assemble your source file, without creating an object file.
       This is so you can find errors in your source.
    C. When you are ready to assemble/build click on the  button.
    D. The  button is used to build a complete workspace.
    E. Once NBASM has completed the assembly, the IDE, if prompted to, will show a build window.  
       See figure 8 below.  Later, you can open this build window again with the  button.



    F. The assembler found 1 diagnostic error, and 1 regular error.  Select the line you want to fix in the
       build window, then click the Goto button and the IDE will scroll until if finds that line, selecting
       the line.
    G. After fixing that line, you may press the  button to show the Build window again.  
       Select a different line, and repeat until done.
    H. Once you have fixed all errors, you should have a message stating that "no errors were found".
       
6.  Creating a new work space
    A. To create a new work space, use the File menu (when no other files are opened) or the Workspace menu.
       You will first see a dialog box like figure 10 below.



    B. You will need to select a .COM project, or an .EXE project.
    C. Make sure to name your source file in the Soure Filename field.
    D. Give it a target name.  i.e.: if you are creating a .COM project and your source file name is "demo.asm"
       then put "demo.com" in this field.
    E. Be sure to create a location for the new project.
    F. Figure 11 below shows the next dialog box that will appear. Select each item you wish to include.
       1. Use .Start Directive:  This will include the .start directive in your source.
       2. Stack Size (bytes):  This will include the Stack directive, and allow you to select the stack size 
          you wish to use.  Must be from 64 to 65534.
       3. Choose the Lowest CPU.  If you want to make sure you don't use any instructions that are higher than
          the .386, then select .386 from the drop down list.  Select .x86 to be able to use all instructions.
       4. Select the library(s) to use.  Standard or extended.
       5. Select the checkbox next to "Create Readme.txt" if you wish to have a readme.txt file included.
       6. If the folder you give in the Location field, doesn't exist, the IDE will ask to create it.
       7. The readme.txt file, if asked for, will contain information about NBASM.  You can simply delete the
          text, if you wish not to read it.
       8. The IDE will store the options you used in the registry for the next time you wish to create another
          project.



7.  Opening an existing work space
    A. You may open an existing workspace using the File menu.  Either Open Workspace, or use the Recent Workspaces
       menu item.  Figure 12 below shows the current work space for the kernel source code for the soon to be
       released book, FYSOS: The System Core, a part of this series.
    B. In the tree toolbar, I have one assembly file, with multiple include files, and one readme file.



8.  Using the Simple Find toolbar.
    A. To find a word in the currently opened document, use Ctrl-F, or the Find item under the Edit menu.
       This will allow you to find a word in the currently opened document only.
    B. If the find function finds the end of the file, it will "flash" the status bar, and start from the
       first of the file.  If no match found, it will show with a dialog.  If a match is found, it will 
       select the match.
    C. F3 will continue the search.
    D. The IDE will place a search word in the Find What field depending on the following conditions:
       1. if no selection is present within the current document, the IDE will take the word from the
          find toolbar list.
       2. if a selection is present within the current document, that selection is placed in the Find What
          field.
       3. if a selection is present within the current document, but the find toolbar word is selected, or
          you have modified the word in the find toolbar, that word is used.
       4. if no selection is present in either case, the word from the find toolbar is used.
       5. if no selection is present and no word is present in the find toolbar, the field is left blank.
          
9.  Using the Advanced Find toolbar.
    A. The conditions for the Find What field initialization in 8.D. above is used here.
    B. Click on the  to show the Advanced Find dialog.
       See figure 13a and 13b below.



    C. The simple find dialog (figure 13a) will find a word or phrase in all files matching the File Types
       field.  Setting the Look in Sub Folders check box, it will recurse through the folders.
    D. All files found will be listed in the View Window Toolbar at the bottom of the app.
    E. If the View Toolbar is not shown before the call, the IDE will show the Toolbar.
    F. Clicking on the Advanced button will show the rest of the dialog.  See figure 13b.



    G. The bottom part of the dialog is used for finding files, not words or phrases within them as the top
       part is used for.
    H. Enter a file search phrase, wild cards allowed, then click on the Find File button.  If a match
       is found, the path will be displayed in the bottom box.  Clicking on the Open button will open
       that file in the current view.  If Close Dialog on Open File is check the dialog box will close.
    I. You can continue to search for files by pressing the now Next File button.  When there are no
       more files found, the button will be disabled and display No More.
    J. A word of caution.  This type of find will only go 16 sub directories deep.

10. Using the Member Popup function.
    A. NBASMIDE will recognize when you are entering in indirect memory accesses with the period or
        arrow (->) operands.  See figure 14 for an example.



    B. This will only work if the ST declaration is in the current open .asm file, or S_MCB struct 
       definition is within the current open .asm file, or any include file, opened or not, that the 
       current open .asm file points to.
    C. Use the arrow keys to scroll up or down, then press enter and NBASMIDE will insert that member name
       into your source code at that position.
    D. Press the ESCape key to cancel.
    E. Be sure that the "Allow Member Popups" check box is checked.


Tips and tricks:
1.  When creating a new file, hold the Left Shift Key to skip the 'new file type' dialog, and create a .asm file.
2.  When creating a new file, hold the Left Ctrl Key to skip the 'new file type' dialog, and create a .inc file.
3.  To move from file to file within the editor, hold down the ctrl key and press the tab key.  This will
    move forward.
4.  To move from file to file within the editor, hold down the shift key, the ctrl button, and press the tab
    key. This will move backward.
5.  When inserting your signature text, hold down the shift key while clicking the sig toolbar button or menu
    item to skip the 'enter signature' dialog.
6.  Shift Right click on an instruction or directive for a popup help window on that item.
7.  Hold down the Left Ctrl key while clicking on the Assemble/Build buttons to create a Listing file even
    if the "Create Listing" check box is not checked.