# Santa's Gift Bag

By Brian Tietz

Copyright 1997-2000

Bug reports (including documentation errors) and feature requests can be sent to briant@timelinevista.com.

Updates available at http://www.be.com/software/beware/development/santasgiftbag.html.

Current version: 3.00

##

## License

The source code, object code, libraries, and the other components of Santa's Gift Bag are being made publicly available and free to use in freeware and shareware products with a price under $25 (I believe that shareware should be cheap). For overpriced shareware (hehehe) or commercial products, please contact me to negotiate a commercial use license. After all, I did work hard on these classes and invested a lot of time into it. That being said, DON'T WORRY I don't want much. It totally depends on the sort of project you're working on and how much you expect to make off it. If someone makes money using my work, I'd like to get at least a little something for my contribution to that profit.

If any of the components of Santa's Gift Bag are is used in a shareware or commercial product, I get a free copy. The source is made available so that you can improve and extend it as you need. In general it is best to customize these classes through inheritance, leaving the original Santa's Gift Bag source code unmodified, so that you can take advantage of enhancements and bug fixes as they become available.

Feel free to distribute any components of this archive, but you are required to keep the documentation and license with it. If you wish to distribute modified versions, also feel free to do so, but do so in such a manner that it is very clear what was modified, why, how, that it is not an official Santa's Gift Bag release, and you are also required to keep the documentation and license with any modified versions.

## Components

####

ArrowButton | GenericTestApp
AutoDeleter | ImageAboutWindow
BetterScrollView | MultiLineTextControl
BufferedFile | NewStrings
ChecksumDataBuffer | PrefilledBitmap
Colors | ScrollViewCorner
ColumnListView | TabView
Cursors | TextEntryAlert
DeepBevelView | TypedBList
DocumentApp | UserResizeSplitView
EndianIndependentFile | WindowPositionSet
FontSensitiveLayoutTools | WrappingTextView

## Overview

#### ArrowButton:

Works just like BButton, but it provides arrows with the standard Be appearance like what is provided with BScrollBar. The implementation needs some work, since it was written before B_ASYNCHRONOUS_CONTROLS.

#### AutoDeleter:

If you new temporary objects in a function with several points of exit, at each of which the temporary objects need to be deleted, it clutters your code. If you instead create an AutoDeleter on the stack, your dynamically allocated temporary objects will be deleted with cleaner code. Also, if you use exceptions, as the stack is unwound until the exception is caught, only stack variables will be deleted, not dynamically allocated ones. If you create an AutoDeleter for dynamically allocated objects, they will be deleted where necessary as the stack is unwound.

####

#### BetterScrollView:

BScrollView replacement that allows you to specify directly the size of your data rect, and the BetterScrollView takes care of the scrollbar proportions and inactivating the scroll bars when the entire content is showing, and provides nice "pulling behavior" to reveal the content when the user is resizing the scroll view bigger.

#### BufferedFile:

Buffers file output for increased efficiency.

#### ChecksumDataBuffer:

Buffers data in an endian-independent manner for network transmission, and can generate a checksum for transmission by multiple methods.

#### Colors:

Provides definitions for commonly used Be user interface colors. Note that you should try to avoid using these when possible, and instead use ui_color and ui_tint. Also provides definitions for many common colors which can't (or wouldn't make sense to) be obtained from ui_color.

#### ColumnListView:

BListView-derived class with columns that the user can resize, drag, sort, etc., with BOutlineListView-like support for hierarchical lists.

#### Cursors:

A couple of commonly needed custom cursors.

#### DeepBevelView:

A BView that draws a deep bevel like that of BTextControl around its perimeter.

#### DocumentApp:

A document file management framework. Provides a BApplication-derived class and a BWindow-derived class which work together to give nice document behavior, automating the process of quitting when the last window closes, prompting to save unsaved documents, etc. etc. It saves a LOT of work because getting perfect behavior in a multi-document application can take hours of coding, testing, and recoding to get it right.

#### EndianIndependentFile:

BufferedFile-derived class to buffer file output for improved efficiency and allows readable code style to still be efficient. Eliminates endian-ness issue by providing automatic byte swapping. Includes a handy ReadString/WriteString pair.

#### FontSensitiveLayoutTools:

A set of classes to facilitate easy font-sensitive GUI layout.

#### GenericTestApp:

Generic test application framework for testing code fragments that need a GUI. Useful for putting together new Classes and also simplest-case code for reporting BeBugs(tm).

#### ImageAboutWindow:

A nice looking about box window that extracts an image file from a specified resource in the application, putting it in a bar on the left hand side, displaying version info from the application version resource, and displaying the specified text.

#### MultiLineTextControl:

Works just like a BTextControl, but allows multiple lines of text.

#### NewStrings:

Wrapper for BFont::GetStringWidths that returns the width of the widest string. strdup, strcat cousins that do their allocation using new.

#### PrefilledBitmap:

BBitmap wrapper that allows you to specify the image data in the constructor.

#### ScrollViewCorner:

A BView for filling the corner of a BScrollView that's not seated in the lower-right corner of a B_DOCUMENT_WINDOW.

#### TabView:

The BTabView implementation is really bad for resizable windows and chokes on hidden child views, TabView handles both cases properly.

#### TextEntryAlert:

A class very similar to BAlert, but which has a text entry box for the user to enter text into, which is reported back to the application when the user dismisses the dialog. It allows control over the BWindow look and feel flags, so it need not be a modal dialog, although that is the normal usage.

#### TypedBList:

A templated BList that adds type checking, since BList's use of void* doesn't allow the compiler to do type checking.

#### UserResizeSplitView:

Provides a user draggable slider to adjust the size of two adjacent views.

#### WindowPositionSet:

A class to make sure that windows are actually visible onscreen when they're created, and to manage the locations of newly created windows to space new windows so that each new window doesn't sit on top of the last one. Gives nice behavior and is easy to use.

#### WrappingTextView:

A BTextView derived class that automates the process of rewrapping the text when the view is resized. Also provides a mechanism for storing the text view contents when appropriate, which is useful if the view is of an object that can exist without the view, so that this more persistent object can be kept up-to-date when the text is modified.

## Revision history

3.0: Started keeping a revision history for Santa's Gift Bag as a whole. Added documentation for all Santa's Gift Bag components. Removed MouseWatcher, since B_ASYNCHRONOUS_CONTROLS fills this need as of R4. Added FontSensitiveLayoutTools. Added UserResizeSplitView. Fixed a bug in MultiLineTextControl (wasn't changing the TextRect in response to resizing). Fixed BufferedPreview in BufferedFile. Fixed behavior of WindowPositionSet.

By Brian Tietz

Copyright 1997-2000

Bug reports (including documentation errors) and feature requests can be sent to briant@timelinevista.com.