Technical Articles

How To Create Scrolling BoxText in WinBatch

David A. Gray, MBA
Chief Wizard, WizardWrx

A frequent request on the WinBatch Technical Support bulletin board, hosted by Wilson WindowWare, is for the ability to display scrolling messages in a window such as the one generated by the native BoxText ( ) function.

Thanks to User Defined Functions and arrays, it has become possible to implement such a feature using a few custom functions, which I explain and offer for download with this article.

How It Works

The magic that makes this feature work is in a standard data structure called a stack, which I implemented as a native WinBatch array.

To simplify things, the array is constructed in a special way.

The array has one dimension, which computer scientists call a list or a vector.
The size of the array is M + 1, where M is the maximum number of elements allowed to occupy the stack.
Array element zero is reserved for three data elements that are used to manage the stack. They are kept in a TAB delimited string.
1. The first element is the value of M, the maximum size of the stack.
2. The second element is N, a positive integer that represents the number of elements that have been used. This information has two uses.
  - It is tested against stack size M to test the integrity of the stack. By definition, N <= M.
  - It is used to locate the end of the used part of the stack, so that unused elements of a large stack need never be processed.
3. The third element is a True/False flag (a Boolean value, for all you geeks) that governs the behavior of the function that pushes data onto the stack when the stack is already full.
  - If this flag is set to False, the stack exhibits classic stack behavior and returns an error code indicating that the stack is already full; the new item is not added.
  - If the flag is set to True, the stack deviates from classic stack behavior by pushing the oldest item off the bottom of the stack to make room for the new item.
Elements 1 through N + 1 contain stack data, with the most recently added occupying element N + 1 and the oldest occupying element 1.
If M > N, elements N + 1 through M contain unpredictable values. If they remain unused, they are uninitialized and must not be directly accessed by user code, as any attempt to do so will cause the WIL run-time library to throw a trappable error. If the cells were used and the stack has shrunk, their contents are unpredictable.

New messages are pushed onto the stack, then a string is constructed by reading the stack from the bottom (element N + 1) up. (The element most recently added to the stack is considered its top. The string is displayed using the BoxText ( ) function.

A Note About the Stack

The standard implementation of a stack has a finite capacity. When the stack becomes full, it is said to be in an overflow state and nothing can be added to it. Because this stack is intended to meet a specific need that requires deviating from this behavior, you must set a flag when you initialize the stack to tell the stack management functions to allow new items to be pushed onto the stack, at the expense of the oldest item, which is lost forever.

However, if you want your stack to behave normally, to be in an overflow state and prevent addition of new items when it is full, initialize the stack with the flag set to @false

Demonstration and test script BoxTextStack_P6C_Test_Harness_2.WBT demonstrates the stack in its normal and deviated configuration. The deviant behavior is used for the demonstration and tests of function BoxTextStack_P6C. Tests 19 through 24 demonstrate normal behavior of the stack, returning an error code of -6 when addition of another item would cause it to overflow.



Meet the Functions

The table below lists and briefly describes the functions.


	
		Function
		Include File
		Purpose
	
	
		BoxTextStack_P6C
		BoxTextStack_P6C.WIL
		This function is called to add a new
			message to the scrolling list (kept in a stack) and to display the messages currently
			held on the stack. You must call function Stack_Init_P6C  once only 
			in order to create a working stack to pass to this function.
		
	
	
		BoxText_P6C
		BoxText_P6C.WIL
		This function is called to add a new
			message to the scrolling list (kept in a stack) and to display the messages currently
			held on the stack. You must call function Stack_Init_P6C  once only 
			in order to create a working stack to pass to this function. This function behaves the same
			as companion function BoxTextStack_P6C would if called with its
			pFlag  argument set to @false.
		
	
	
		Stack_Init_P6C
		StackLib_P6C.WIL
		Create a stack of size M,
			returning the empty stack, ready to use. You must call this function before your first
			call to function BoxTextStack_P6C  because you must pass that function a
			working stack. This function is called once  per stack, though you may create and
			use as many stacks as you need.
		
	
	
		StackPop_P6C
		StackLib_P6C.WIL
		Given a stack returned by a call to
			Stack_Init_P6C, pop the element pushed onto the stack by the last call to
			StackPush_P6C.
		
	
	
		StackPush_P6C
		StackLib_P6C.WIL
		Given a stack returned by a call to
			Stack_Init_P6C and a string, integer, or other scalar data, push 
			the scalar data onto the stack.
		
	
	
		MessageBox_P6C
		MessageBox_P6C.WIL
		Though not required for the task at hand,
			I included this function because the test harness uses it to display standard Windows
			message boxes. This function replaces the xMessageBox function from the
			WILx extender library that ships with WinBatch.
		
	


Immediately below the #DefineFunction line in each function definition is a large
	comment box that fully describes each function, its arguments, its return values, and everything
	else you need to know in order to use it. The archive that accompanies this article also contains
	BoxTextStack_P6C_Test_Harness_2.WBT, a WinBatch script that exercises the functions
	and demonstrates how they are used. File BoxTextStack_P6C_Test_Harness_2.WBT is a
	text file generated by running the script.


Contents of Article Download File

Zip archive Scrolling_BoxText.zip contains everything discussed in this article.
	The table below summarizes its contents.



	
		File Name
		Description
	
	
		BoxTextStack_P6C.WIL
		This include file contains function
			BoxTextStack_P6C.
		
	
	
		BoxText_P6C.WIL
		This include file contains function
			BoxText_P6C.
		
	
	
		BoxTextStack_P6C_Test_Harness_2.TXT
		This text file is the log generated by
			executing WinBatch script BoxTextStack_P6C_Test_Harness_2.WBT.
		
	
	
		BoxTextStack_P6C_Test_Harness_2.WBT
		This WinBatch script demonstrates the use of
			the functions in the three .WIL files.
		
	
	
		MessageBox_P6C.WIL
		This include file contains function
			MessageBox_P6C.
		
	
	
		StackLib_P6C.WIL
		This WinBatch include file contains all
			three stack management functions: Stack_Init_P6C, StackPop_P6C,
			and StackPush_P6C.
		
	




Code Revision History


	
		Date
		Who
		Description
	
	
		05/16/2004
		DAG
		Initial public release.
	
	
		05/17/2004
		DAG
		Rewrote stack maintenance code in
			StackPop_P6C, and StackPush_P6C so that there is no data
			movement unless the stack is full and older items must be removed and to support
			canonical stack behavior as documented in standard computer science texts on data
			structures.
		
	
	
		05/21/2004
		DAG
		Add new BoxText_P6C  function.
	




Support

The contents of Zip archive Scrolling_BoxText.zip are supplied as is  and are
	not officially  supported. However, we shall field inquiries submitted by email on a best
	efforts basis. Please submit your inquiries using
	this form.


Copyright

Article and contents of Zip archive Scrolling_BoxText.zip 
	Copyright 2004, Simple Soft Services, Inc., d/b/a P6 Consulting.
	Copyright 2005, Simple Soft Services, Inc., d/b/a WizardWrx.
	All rights reserved world wide.


Nevertheless, you are hereby granted a non-exclusive license to use the enclosed WimBatch functions
	(the contents of the three .WIL files) in your own applications (in both source and
	object form) and to freely redistribute the source files and compiled code, so long as you meet
	all of the following simple conditions.


	You retain the original copyright notice on the source code.
	You distribute test script BoxTextStack_P6C_Test_Harness_2.WBT  and
		MessageBox_P6C.WIL if you redistribute BoxTextStack_P6C.WIL 
		or StackLib_P6C.WIL.
	
	If you change the code in any way whatsoever, you fully describe the changes in the
		Maintenance Log section of the comment box at the top of the affected function.
	


If you have any questions about what is allowed and disallowed by the above terms, please feel free to contact the author using this form.





	
		Download Scrolling_BoxText.zip
	






	
	

	
	
	

	
	Copyright and Legal Notice
	

	
	Last Updated 19 August 2006
	
	© 2006, WizardWrx. All rights reserved world wide.

Function	Include File	Purpose
BoxTextStack_P6C	BoxTextStack_P6C.WIL	This function is called to add a new message to the scrolling list (kept in a stack) and to display the messages currently held on the stack. You must call function `Stack_Init_P6C` once only in order to create a working stack to pass to this function.
BoxText_P6C	BoxText_P6C.WIL	This function is called to add a new message to the scrolling list (kept in a stack) and to display the messages currently held on the stack. You must call function `Stack_Init_P6C` once only in order to create a working stack to pass to this function. This function behaves the same as companion function `BoxTextStack_P6C` would if called with its `pFlag` argument set to `@false`.
Stack_Init_P6C	StackLib_P6C.WIL	Create a stack of size M, returning the empty stack, ready to use. You must call this function before your first call to function `BoxTextStack_P6C` because you must pass that function a working stack. This function is called once per stack, though you may create and use as many stacks as you need.
StackPop_P6C	StackLib_P6C.WIL	Given a stack returned by a call to `Stack_Init_P6C`, pop the element pushed onto the stack by the last call to `StackPush_P6C`.
StackPush_P6C	StackLib_P6C.WIL	Given a stack returned by a call to `Stack_Init_P6C` and a string, integer, or other scalar data, push the scalar data onto the stack.
MessageBox_P6C	MessageBox_P6C.WIL	Though not required for the task at hand, I included this function because the test harness uses it to display standard Windows message boxes. This function replaces the `xMessageBox` function from the `WILx` extender library that ships with WinBatch.

File Name	Description
BoxTextStack_P6C.WIL	This include file contains function `BoxTextStack_P6C`.
BoxText_P6C.WIL	This include file contains function `BoxText_P6C`.
BoxTextStack_P6C_Test_Harness_2.TXT	This text file is the log generated by executing WinBatch script `BoxTextStack_P6C_Test_Harness_2.WBT`.
BoxTextStack_P6C_Test_Harness_2.WBT	This WinBatch script demonstrates the use of the functions in the three `.WIL` files.
MessageBox_P6C.WIL	This include file contains function `MessageBox_P6C`.
StackLib_P6C.WIL	This WinBatch include file contains all three stack management functions: `Stack_Init_P6C`, `StackPop_P6C`, and `StackPush_P6C`.

Date	Who	Description
05/16/2004	DAG	Initial public release.
05/17/2004	DAG	Rewrote stack maintenance code in `StackPop_P6C`, and `StackPush_P6C` so that there is no data movement unless the stack is full and older items must be removed and to support canonical stack behavior as documented in standard computer science texts on data structures.
05/21/2004	DAG	Add new `BoxText_P6C` function.