Waffle's IDE v2.0

Waffle's IDE v2.0

Thankyou for trying my IDE. Version 1 had many-many features and became too unusuable. This I decided to tone it down and focus instead on things truely needed, or at least features I though DBC lacked. Actually, I use Dark Edit 1.56 by Guy Savoie in 2000. Some don't like it, but I do because it was simple (I don't use the advanced features) and it works fast (well), faster than mine.

For my IDE, I felt it needed features that nobody else seems to be adding to other IDEs; such as context help and Debugger Options. I also did a sorta keyword-tips thingy to provide a parameter list for a keyword at the bottom of the window. Those are the KEY features. The keyword-tips was done mainly because I can never remember all the settings for the command "Set Object ........." and it is much nicer to have a little reminder. I know some like a "code injector" thingy, but I don't. Things get pretty cluttered with multiple windows open, and I like to keep things simple. Some IDE use "Tabbed" windows to keep things clean looking, but I prefer MDI for viewing code side by side. Very usefull for examples and such.

Features

Context Help
Displayes Dark Basic Classic help for keyword when you press F1
Compiler Directives
Adds additional variables before compiling project.
Integrated Packer
Automatically create self extracting Pack files after builds to prepare your application for distribution
Debugger Options
Adds additional special code for tracking down difficult bugs
Macro Support
Create macros that can be used for all include files in project
Project Window
Lists all Functions, Macros and Labels used by all open files
External Tool Support
Customizable menu for launching external tools
Improved Error Reporting
Reports correct module the error occures in
Scintilla
My editor uses Scintilla. Not customizable at this time

Using The IDE

File Menu:
Enables you to Open, Close or create a New empty code window. This will also maintain a list of the last 10 code modules you have opened.

Edit Menu:
Enables Cut, Copy and Paste to or from the clipboard. At the bottom is an Undo option that can Undo the last edit operation in the code window.

Search Menu:
Calls up the search and Replace dialog. You can also use F3 to continue a search operation.

Debug Menu:
Bested explained here.

Compile Menu:

Compile - Check source for Errors
Execute - Execute Source Code
Make EXE Create a stand alone application without including any media
Final EXE with Media Create a stand alone application and include media
Directives - Display Compiler Directives
Make Pack File - if Pack Options are all set, will make a self extracting pack file.

Tools Menu:

Configure Tools - Displays Tool Manager
Preview Media - Will try to present media at cursor with the best tool from available tools
Edit Media - Will try to edit media at cursor with the best tool from those available
Browse Media - Opens a file browser an inserts the file name selected into the source at the current position
Insert Color - Opens a color browser and inserts the color at the current position as RGB(R,G,B) from your selection
All your custom tools will be listed here

Window Menu:
The only important one here is the one at the top; "Hide Project Window" is for hiding or showing Project Window. All currently open windows will be list at the bottom of this menu

Help Menu:
Displays information about various topics.

Back to Top
Toolbar Icons
Contacts

Tool Bar Icons

Most of the common things you need to do can be quickly completed via the Tool Bar.

This will open a new code window

This will open a browser window permitting you to open an existing code file

The will save the changes in the current code window

This will close the current window and ask if you wish to save if you have made any changes

Will cut selected text from the current window to the clipboard

Will copy selected text to the clipboard

Will paste text from the clipboard to the current code window

Will open a dialog permitting you to scan for selected test in the code

This enables extra debugging code

Turns off debugging code

Compile Source. This checks for errors without executing code

Execute code. This does not build executables.

Makes a stand alone *.exe file without included media

Makes a stand alone *.exe with included media

This calls up the Compiler Directives window

This hides or displays the Project Window

This cycles through all open windows

This shows this really cool help file

Back to Top
Using the IDE
Contacts

Help Viewer

This is just your basic htm viewer. I use this for both Dark Basic Help and for my own htm help files. For context help, just click on a keyword. When the keyword tip is displayed (not all keywords are supported) press F1 to obtain extra detailed help on that keyword. Very nice feature. You can also type in a keyword at the top and click go to search for another keyword. This also properly supports the display of examples.

Back to Top
Using the IDE
Contacts

Project Viewer

This displays all targets (functions, macros and labels) used by all open code windows. It also has a table listing ASCII codes and SCANCODE() values. This does not update in real time. You can force a refresh by clicking the refresh button on the toolbar. If you double-click on a target, that code window will be brought to the front and that line will be displayed. Click the Project Window toolbar button to toggle the display of the project window. You can also use the Window - Hide Project Window menu option.

Back to Top
Using the IDE
Contacts

Error Reporting

In the event of an error during compiling, your build will be canceled and (in then event of enabled compression) compressions will not occure. My IDE will try and locate the correct model (#INCLUDE) holding the error and place a marker (in red) in the margin next to that line. The Error will be reported in the status bar, but will be overwritten on the next keyword tool-tip. In the event the error should occur in a macro , only the call to the macro will be marked. It would be up to you to decide if the actual error is in the macro definition or in the call. To help you determine that, you can use the Project Window to quickly jump to the macro. You can also open the file "FullDBCFile.dba" to see how your macro was expanded in the source.

Back to Top
Using the IDE
Contacts

Macro Support

Dark Basic does not support Macros.Guy Savoie tried it with Dark Edit but it was rather cumbersome, and would confuse the error reporting and only work for the current code module. Mine is much more versitile. It works accrossed all project modules (#INCLUDE) and reports the correct error line. Mine works this way by combining all sources into one file before sending to the compiler. I also add extra markers to the source to help in tracking error line numbers. Generally, you don't need to know the details, but from time to time you will need to be "aware". You can examine this file at any time by opening the file "FullDBCFile.dba". This is usefull when you have a macro that does not work as expected. Or for when you have a question about which line the error really is on, I may have a few mistakes here.

Macro Types

Simple
These are single line, simple substitution macros in the format:
Macro MySimpleMacro As DarkBasicCode
Example
Macro BLUE as RGB(0,0,255)
Now, everywhere you place "BLUE" the code "RGB(0,0,255)" will replace it during compilation
MultiLine 2 Parameter
These can be used to do slightly more fancy things and follows the forms
     Macro MacroName Var1 = Var2
     Macro MacroName Var1 , Var2
     EndMacro
Example:
Macro Global V1 = V2
   Macro V1 As V1~(1)
   Dim V1
   V1 = V2
EndMacro

This shows the value of a nested Macro and shows the concatination character "~" in use. This would be a multi-pass macro that defines another macro on the fly. If you call this macro as:
Global X = 34
after the first pass this is converted to:
Macro X as X(1)
Dim X
X = 34

after the second pass it becomes:
Dim X(1)
X(1)=34

And, anywhere in code where you use X, this will be replaced by X(1)
Multiline Multiple parameters
Follows the form:
Macro MacroName(V1,V2,V3, ....)
EndMacro
And you call this macro as "MacroName(V1,V2 ....)"

Multiline macros get two extra tags added to help with determining the actual error line. So the complete macro replacement looks like

`Macro Global X = 34
dim X(1)
X(1) = 34
`EndMacro

Back to Top
Using the IDE
Contacts

Debugging Options

Dark Basic Classic does not always report the correct error, sometimes your application terminates without a reason or sometimes you get a "Global Protection Fault" (system crash) and need some way to quickly locate it. I created some special debug settings and options to help locate these kind of bugs. For even extra support, you can enable compiler directives and check Enable Directives, and check CompilerDebug so you can check debug settings in your code.

Debug Menu:

Debug Off
Prevents adding additional code to your source code
Debug On
Enables the placing of addition code into your source during testing to track down bugs
Clear all Break Points
Scan current source code for "Break" and removes those lines.
Set Break Point
Inserts a break point at the current position. This inserts the text 'Break "1234 Module"'. Where 1234 is the current line number and Module is the code module.
Clear Log Points
This removes all log points created by "Set Log Point" by scanning the current source for "`LOGPOINT" and removing those 5 lines
Set Log Point
This will create a Log Point at the current position. A Log Point will save information to the clipboard for later use. This inserts the following code:

     `LOGPOINT
     MSG$=GET CLIPBOARD$()
     MSG$=MSG$+"1234 Module"
     MSG$=MSG$+CHR$(10)
     WRITE TO CLIPBOARD MSG$

where "1234 Module" refers to the current line number in module. As you can see, this creates a list of all points reached in your application. If a crash occurs, you can view this log to see the last point logged and use that as a starting point for additional testing.
Log All Functions
This works simular to Set Log Point, but does more. Whenever a function is called, it is logged and time-stamped. When the function is finished, it is also logged and time-stamped. This serves to track how much time is used by a function call.
Sync All Objects
This will place a "Sync" command after all object functions. This option will have dire consequences and should be avoided. This will cause a major slowdown of your application,
BUT
This will trap those errors that relate to invalid object numbers. Dark Basic Classic seems not to check those until a Sync command occurs. This is just another methode to try and track those. Using Break Points with Sync Break Points may be better for large projects
Sync All Break Points
Adds a Sync command after all Break Points
Sync All Log Points
Adds a Sync command after all Log Points
Clear All Sync Points
Quickly Unchecks all Debug Menu Sync Options
View Log
After a run, you can view the log file. Each entry will be on its own line and can tell you alot about your program

Compiler Directives

Most other IDEs do not have this option. Dark Basic Classic technically does not have any compiler directives. These options are added by adding additional variables to the source code or doing things after a build. To display the Compiler Directives dialog, use the Compile - Directives menu option

On the left are Directive Options while on the right are Compression Options.

EXE Name
DarkBasic uses the filename of the *.dba file. Check this box if you desire to use a different name
Command Line
This scans your source code and replaces "CL$()" with the text you provide here during Executing, not during a build
Use Icon
After a build, this will change the default DB icon with your icon file. Only 32x32 icons supported at this time. The Browse button will enable when checked. Use this button to locate your Icon (*.ico). The button will rename to the selected icon file.
Enable Directives
This enables the insertion of extra variables into your source code
CompilerTime
Saves the current build time in the DBC Variable CompileTime$(1). Usefull for version tracking of errors.
CompilerBuild
Saves the current build setting as CompileBuild$(1). This will be set to "Compile", "Execute" , "Make EXE" or "Make Final with Media".
CompilerDebug
This will save Debug Options in source. CompileDebugOn(1), CompileLogFunc(1), CompileObjSync(1), CompileBreakSync(1), CompileLogSync(1)
CompilerPack
Saves Compression options as CompilePack$(1). This will be set to "No Compression", "Make Run Time Compression", "Make Stripped Compression", "Make Patch", "Standard Compression"
CompilerCustom
Enables custom Directives. Will enable the Add, Edit and Del buttons to manage user definable directives.
Add
Add a new custom directive. This pops up a small dialog asking you to describe your directive as a DBC variable. Your custom directive should be defined as:
     CustomString$(1)="My Custom String Value"
     CustomInteger(1)=IntegerValue
     CustomFloat#(1)=FloatValue
Edit
Edit an existing custom Directive
Del
Delete an existing custom Directive

Compression Options:

I added a self extracting compressing tool that is integrated into this IDE. The compression is slow, but extraction is lightning fast and very small. The various options are for determining when to compress and how to compress. You can also add extra files to the pack, such as source, or help files.

Packing Methods:

No Compression
Disables compression
Make Run Time Compression
This creates a Dark Basic Classic file called "Runtime.001" and then packs it to a self extracting file called "pRuntime.exe". This file should not be distributed as a stand alone application. This file holds the Dark Basic Classic Interpreter only. Also be aware that there are multiple versions of DBC and therefore this file may be incompatible with other versions of DBC. This is usefull for making your distributed files smaller
Make Stripped Compression
This is designed to work with "Runtime.001" which must be created first before this can be done. This creates a file "exename.002" which is then packed as a selfextracting file called "pexename.exe". This file should not be distributed as a stand alone application. During extraction, the self extractor will look for the file "Runtime.001" in the same folder as itself. If it is not present, extraction will fail. If it is present, "Runtime.001" is merged with "exename.002" to create "exename.exe" thus restoring your application.
Make Patch
This builds a file called "exename.pat" which is then compared to "exename.exe" to create a patch file called "exename.wpk". This is then made into a self extractor called "pexename.exe". During extraction, the extractor will look for the file "exename.exe" and rename it "exename.bak". This file is then compared to exename.wpk and your new exe file is created
Standard Compression
This creates a self extracting exe file called "pexename.exe" containing your file "exename.exe" and any extra files you have listed for packing. Do not include files that are not in your project's directory or subdirectory because those may not extract properly
Compress on EXE build only
Makes a standard compression only after a successful exe build
Compress on Final builds
Makes a standard compression only after a successful exe build that has included media
Compress on ALL builds
Makes a standard compression after any successful build

Manual Packing:

You can create a self extracting pack file manually by opening the Compiler Directives and setting the compression options and then clicking the Pack button. If the options are already set, you can also just use the Compile - Make Pack File menu option.

Packing Non-DarkBasic Files:

This is not really supported, but here is a hack methode to make a self extracting pack file for any "exe" file.

Open a new code window and save it as "blank.dba". You will need to save this into the same path as the "exe" file you wish to pack. This will create another file "blank.dir" for saving Compiler Directives and compression options.
Then, check the Exe Name check box and enter the exename for the file you wish to pack. Actually, you can use any name for the Exe Name permitting you to pack web pages (*.htm,*.html).
Set compression options. to "Compress on All Builds". This will enable the "Pack" button and the Add/Del files buttons.
Add any extra files to pack with the "exe" (such as media files)
Then click the "Pack" button to pack your files to a self extracting pack called "P+yourexename.exe".
When you close this, you can return to these settings by opening your original file "blank.dba" which will restore your compression options. including the file list.

Thats it. Not too difficult was it?

Back to Top
Using the IDE
Contacts

Managing External Tools

Click on Tools - Configure to bring up the external tool manager. I tried to keep this window nice and clean. On the left will be your list of tools, in the same order as displayed in the tool menu. Even the same name. Also listed is the full path to the tool and the command line options you desire for the tool. The buttons on the right are for acting on this list.

Add
Adds a new tool and opens the Edit dialog to complete the setup
Del
Deletes the selected tool from the menu
Edit
Edit the current settings for the selected tool
Help
Brings you to here
Cancel
Cancel any changes to the menu then close
OK
Save changes to the menu and close

Configure External Tool

This dialog is just a little complicated. Don't worry though, most settings are not needed.
The big button on the top left (it says "FileName" if you are Adding a new tool) is for selecting your tool. When you click this button, a browser will open for the selection of your tool. After you have found your tool, this button will rename itself to your tool.

Below this is the Menu Name. Change this to say whatever you want displayed in the Tool Menu.

If you do not need any advanced options, just click the OK button to save the changes and go back to the Tool Manager

Additional Options:

Commandline
Any commanline switches or other settings your external tool may require
Context Open
Check this to enable your tool to open files under the cursor by using the Tool - Preview Media or Tool - Edit Menu option. You will also need add a list of file types that your tool supports.
Change Ext
Check this if you need to change the file type before opening the file. Then provide the file extension you need to change it to. This only applies to the Tool - Edit Menu Option. Usefull if you need to edit a *.X file as a *.MS3D file for example.
Copy Current Line
Check this if your tool expects this text in the clipboard
Copy All
Check this if your tool expects the full text in the code window
Paste Clipboard
Check this if your tool places information onto the clipboard. This option has no effect unless "Wait for Exit" is checked
Wait for Exit
Check this if you want to wait for your tool to close before continuing.
Index
This is a number that shows the position of your tool in the Tool menu. You can change this to move your tool, or click DEF to reset this to the default value
OK
Save tool settings and return to Tool Manager
Help
Takes you here
Cancel
Cancel tool changes and return to Tool Manager

Visit my website www.archonrpg.com online for more fun free things.
Or email waffle if you have any questions.

License for Scintilla and SciTE

Copyright 1998-2003 by Neil Hodgson < neilh@scintilla.org > All Rights Reserved
Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation.

NEIL HODGSON DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL NEIL HODGSON BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.