Prog_Bar.Lib ============ A progress bar link library for Amiga Programmers ================================================= Written by Allan Savage © 1996/1997 =================================== Introduction ============ Prog_Bar.lib is a progress bar link library designed to make it easy to create, manage and delete progress bars within most programming languages. It has been tested using Dice C, Devpac 3 Assember, SAS/C and Turbo Modula-2. The library is easy to use and provides a large range of options for your progress bars. It has been designed to operate in a similar way to the GadTools functions for managing gadgets, so the ideas involved should not be new to anyone who might be using them. The library is capable of producing many different types of progress bars using a simple set of parameters. These allow the programmer to completely customise a progress bar by changing its border, colours, size, location, dimensions, direction and text. To give you an idea of what is possible using this system I have included a few demonstration programs complete with source code so that you can learn from the techniques used to control a progress bar. Installation ============ How to install and use the library really depends on which environment you want to use it in. I will provide a general outline of the various stages and a more detailed description of how I installed it with each system. In each case you may be using a different system, but if you follow the general guidelines you should not have much difficulty. I will also show the commands I used to compile and link the demo programs for each system. The documentation includes an Amigaguide file called prog_bar.guide . This contains a detailed description of each function and can be copied to your compiler's document directory, or can be linked into the Autodocs documentation if you have it installed. A plain text version of this file is also supplied. It is called "prog_bar.doc". C Installation -------------- The C system is comprised of two files, "prog_bar.h" and "prog_bar.lib". "prog_bar.h" should be copied to anywhere on your compiler's include file search path. Just make sure you know where you put it because you will need to #include it any time you want to use prog_bar. For Dice I created a directory called "DINCLUDE:library" and copied it to there. "prog_bar.lib" should be copied to anywhere on your compiler's library search path. Alternatively you could put it anywhere and then specify its full pathname when linking. In Dice I copied it to "DCC:dlib/" Assembler Installation ---------------------- The Assembler system is comprised of two files, "prog_bar.i" and "prog_bar.lib". "prog_bar.i" should be copied to anywhere on your assembler's include file search path. Just make sure you know where you put it because you will need to include it any time you want to use prog_bar. For Devpac I copied it to the "Devpac/include/libraries" directory. "prog_bar.lib" should be copied to anywhere on your assembler's library search path. Alternatively you could put it anywhere and then specify its full pathname when linking. In Devpac I copied it to "Devpac/lib/" Modula-2 Installation --------------------- The Modula-2 system is comprised of three files, "prog_bar.def", "prog_bar.sym" and "prog_bar.lib". "prog_bar.def" should be copied to anywhere on your compiler's include file search path. Just make sure you know where you put it because you will need to import it any time you want to use prog_bar. For Turbo Modula-2 I copied it into the "Modula_2/amiga/" directory. "prog_bar.sym" should be copied to your compiler's symbol file directory. If the "prog_bar.sym" file is not of the correct format for your compiler you will need to recreate it. This is done by compiling "prog_bar.def". For Turbo Modula-2 I copied it into the "Modula_2/sym/" directory. "prog_bar.lib" should be copied to anywhere on your compiler's library search path. Alternatively you could put it anywhere and then specify its full pathname when linking. For Turbo Modula-2 I copied it into the "Modula_2/lib/" directory. N.B. I have my copy of Turbo Modula-2 installed in the "Modula_2" directory. Usage ===== General Description ------------------- Using the system should now be (almost) as simple as using any of the operating system libraries. When you write a program which needs a progress bar just include the relevant definition file at the top of your source and remember to link your object file to prog_bar.lib. The only other requirements are that the Intuition, Gadtools, Graphics and Utility libraries are opened by your program. To actually create and handle a progress bar within your program you will need to follow the rough guide given below. However, every situation is different so you might need to vary your approach. All the available functions are documented in the function list. N.B. Because all of the necessary functions will be linked into your final executable it is completely unnecessary to open the library at runtime. Step 1. Work out what size your bar has to be. Note that the size is the value represented by the full bar. It is not related to the bar's actual dimensions. How you do this will depend on what you are using the bar for. For example, if you want to represent a percentage the size might be 100. If you wanted to use a progress bar while printing the size might be the number of lines to be printed. WARNING : Making the bar too large and then updating it to every stage will probably be very slow. It might also be completely unnecessary. For example, if you define a bar which is 250 pixels wide (excluding borders) and which represents a value of 50,000, then each pixel will represent a value of 200 (50,000/250 = 200). i.e. Updating one unit at a time will require 200 updates before the bar will change. The only exception to this is if the bar's value is displayed as text, but this would probably change too quickly to be of any real value. Step 2. Create a suitable progress bar using CreateProgBarA() or CreateProgBar() . Step 3. Every time you want to change the progress bar, you should use UpdateProgBar() to display the new position. For the examples above this would mean updating the bar after one percent, or after printing each line. It is not necessary to update the bar one value at a time. If the value of the bar is decreasing and you have the text function activated, it will probably be necessary to call ClearText() immediately before updating the bar. This is not necessary if the text is centred within the bar, or if the length of the text does not decrease. Step 4. When you have finished you should delete the progress bar and release the memory used by calling FreeProgBar() . Step 5. When your window needs refreshed you should call RefreshProgBar() . Using Prog_Bar in C ------------------- When writing your source you will need to include the file "prog_bar.h" before you use any of the functions, otherwise the compiler will complain about undefined structures, etc. In Dice I use the line "#include ". When compiling you will then need to tell the compiler to include the code for the prog_bar functions. This is done by linking your code to "prog_bar.lib". In some compilers, or with large multi-module programs, it will be necessary to compile your source to *.o files, and then link these and prog_bar.lib together to produce the executable. If your program is a single source file then you might be able to compile it and link to prog_bar.lib in one instruction. Your compiler documentation will contain more detailed information about this. To compile the demo with Dice I was able to compile the source and perform the link in one operation. The command line to do this was "dcc -2.0 -// -Tt: -o Demo Demo.c prog_bar.lib". Calling the prog_bar functions uses exactly the same notation as any other C function, e.g. "ClearProgBar(PBar);". Using Prog_Bar in Assembler --------------------------- When writing your source you will need to include the file "prog_bar.i" before you use any of the functions, otherwise the assembler will complain about undefined symbols, etc. In Devpac I use the line "include libraries/prog_bar.i". To produce your final executable you will need to assemble your source as a linkable file. The resulting *.o file will then need to be linked with Prog_Bar.lib. To create the demo program with Devpac I created my source in a directory called "Devpac/Progs". From here the command to link the executable was "BLINK demo.o TO demo LIB /lib/prog_bar.lib". Your assembler documentation will contain more detailed information about assembling and linking programs. Calling the prog_bar functions can be done in one of two ways (at least for most of them), namely stack based, and register based parameter passing. All the functions can be used with the stack based method, and most of them can be used with the register based method. If register based parameter passing is supported by a function, the function list will tell you which registers are used. To call a prog_bar function using the stack based method you must place its parameters on the stack in the reverse order, i.e. right to left. Each value you place on the stack MUST be a longword value, even if the parameter type is a word or byte value. To actually call the function you just use a JSR instruction. The target of the jump will be the function name preceded by an underscore, e.g. to call CreateProgBar() you use the instruction "JSR _CreateProgBar". When the function returns you are responsible for removing its parameters from the stack. Any return values will be in the register D0. To call a function using the register based method you simply place its parameters in the relevant processor registers and call the function using a JSR instruction. This time the target of the jump will be the function name preceded by an "@" symbol, e.g. to call UpdateProgBar() you use the instruction "JSR @UpdateProgBar". Again any return values will be in register D0. An example demonstrating the difference is this small piece of code which calls UpdateProgBar() using both methods. UpdateProgBar ( PBar_Ptr, Value ) * Stack Based move.l Value,-(sp) ; Place Value on Stack move.l PBar_Ptr,-(sp) ; Place PBar_Ptr on Stack jsr _UpdateProgBar ; Call UpdateProgBar() lea 8(sp),sp ; remove parameters from stack ; 2 parameters * 4 bytes each = 8 * Register Based move.l PBar_Ptr,A0 ; Place PBar_Ptr in A0 move.l Value,D0 ; Place Value in D0 jsr @UpdateProgBar ; Call UpdateProgBar() Value dc.l 50 PBar_Ptr dc.l 0 Using Prog_Bar in Modula-2 -------------------------- When writing your source you will need to import the file "prog_bar.def" before you use any of the functions, otherwise the compiler will complain about undefined structures, etc. In Turbo Modula-2 I use the line "IMPORT P := prog_bar". When compiling you will then need to tell the compiler to include the code for the prog_bar functions. This is done by linking your code to "prog_bar.lib". Your compiler documentation will contain more detailed information about this. To compile the demo with Turbo Modula-2 I just added "prog_bar.lib" to the end of my compile command. The resulting command line to achieve this was "m2b Demo prog_bar.lib". Calling the prog_bar functions uses exactly the same notation as any other Modula-2 function, e.g. "P.ClearProgBar(PBar);". Demonstration Programs ====================== The Library can currently be used from Modula-2, C and Assembly Language. I have included small example programs in each language so that you can test the library with your compiler before writing anything of your own. All Programmers --------------- The demo program written in C is by far the largest of the demo programs. C is my preferred language so I used this program as a complete demonstration of everything the library can do. As such it is probably worth looking at even if you do not normally program in C. Assembly Programmers -------------------- This is a small program which creates a progress bar and then slowly fills it. When full, the bar is reset and the process repeats. Just click on the Window's Close gadget to end the program. Modula-2 Programmers -------------------- This is also a small program. It fills a progress bar in steps of 1, then changes the direction, border and text mode of the bar, and then fills it again in steps of 5. You just have to wait until it has finished. Distribution ============ Prog_Bar is Copyright © Allan Savage 1996/1997. All Rights Reserved. Prog_Bar is freely distributable, providing that no commercial gain is made from its distribution, and no modification is made to the original archive. Anyone wishing to include Prog_Bar on a magazine coverdisk or other similar collection, or use it in any application, commercial or otherwise, have my full permission. All I ask in return is to be acknowledged somewhere in the documentation and to be told about it (preferably by e-mail). Disclaimer ========== This software is provided "AS IS" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The author does not guarantee the use of, or the results of the use of, this software in any way. In no way will the author be held liable for direct, indirect, incidental, or consequential damages to data or equipment resulting from the use of this software. Acknowledgements ================ The Demonstration program was compiled using DICE v2.07.56 R and its interface was designed using GadToolsBox v37.300. Thanks to Matthew Dillon and Jan van den Baard for these excellant programs. Many thanks also to Roberto Bizzarri for his assistance in testing Prog_Bar v1.01 with SAS/C. How to contact me ================= If you have any suggestions for improving Prog_Bar, bugs to report or queries about the program, please send them to me at one of the addresses below. E-Mail : asavage@bitsmart.com (preferred option) Post : Mr. Allan Savage 2 Navar Drive Gransha Road Bangor N. Ireland BT19 7SW For further information and program updates you might also like to check prog_bar's support page on the World Wide Web. It can be accessed from my homepage at "http://www.netforward.com/bitsmart/?asavage". Program History =============== V1.04 10/10/97 - Rearranged the Prog_bar structure to achieve word alignment. This allows Prog_bar to be used on a 68000 based machine. V1.03 20/07/97 - Minor bug fix. Bars with a value of zero were previously displayed as one pixel in size. Now they will be completely empty. - Added version string. - Added extra validation. It is no longer possible to create a bar which has a size of zero. If you try you will get a bar with a size of one. - Improved rendering of small progress bars. Weird things no longer happen if the progress bar is too small. - Minor bug fixed when calculating position of text. The text no longer disappears if it is taller/wider than the progress bar, unless it is centred. - Documentation updated. - Introduction of the Prog_Bar Support Web Page. V1.02 03/03/97 - Removed the need to link with amiga.lib. - Added support for registerised argument passing. V1.01 11/01/97 - Rewritten in Assembly language. Now works with all compilers (hopefully). - Added definition files for Assembler and Modula-2. - Added Demo programs for Assembler and Modula-2. V1.00 13/12/96 - Initial Release. (Only worked with Dice)