TabBook Widget

The TabBook Widget

1. Copyright

Copyright 1995 Computer Generation, Inc. You may reproduce this document without charge provided the copyright and disclaimer notices appear. The software described in this document is copyrighted under separate terms. See the source code available at ftp://ftp.compgen.com/pub/widgets/TabBook.tar.Z

The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall Computer Generation, inc. nor the author be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

The author welcomes comments and suggestions.
Gary Aviv
Computer Generation, Inc.,
gary@compgen.com
404-705-2811

If you wish to be on an Emailing list regarding this or other CGI widgets, please send a request to the above address. You will be notified when this or other widgets are upgraded or when new widgets become available.

2. Introduction

TabBook is a Motif manager widget which is similar to Motif's own XmNotebook widget in appearance. It is significantly less complex and easier to use, though it has fewer features. It is intended for installations that lack Motif 2.x or just want basic notebook like functionality.

TabBook sets up a series of "Tabs" along the top of a "page" area. Children of TabBook must be either push buttons or manager widgets (such as forms, bulletin boards, row-columns, etc. or a nested TabBook.) The push buttons are dressed with tab like borders and arranged horizontally. The child manager widgets are positioned in the page area so they overlap. There should be an equal number of manager and push button children. The page area is sized to fit the largest child manager.The overall TabBook widget then expands horizontally, if required, to fit all its tabs.

There is one active page at a time. Its corresponding tab is drawn to appear "on top" and attached to the page. The user may press any tab to bring up its corresponding page and the associated manager widget.

TabBook inherits behavior and resources from Core, Composite, Constraint, XmManager, and XmBulletinBoard.

The class pointer is xcgTabBookWidgetClass.

The class name is xcgTabBook.

TabBook reliance on Motif is minor. It consists of inheriting behavior from XmManager, and XmBulletinBoard, setting resources in XmPushButton, knowing when a widget is an xmManagerWidgetClass subclass, and using XmGetColors. It should not be difficult adapting TabBook for use with other widget sets.

3. Version Information

Initial.

4. Distribution Kit

The source distribution kit contains the following files:

TabBook.c TabBook.h TabBookP.h: The TabBook widget source code
TabBookTest.c: A small demonstration program
Imake: an Imake file to build TabBookTest.c.
TabBookTest.make: A hand coded make file for several common OSs in case Imake fails.
TabBook.html TabBook.txt: Documentation in HTML, and plain text formats

TabBook has been compiled successfully on NCR MPRAS, Digital OSF/Unix, Linux, and probably many others.

To build the test program:

	xmkmf
	make

5. Resources

TabBook adds the following resources to those it inherits. The resource class is obtained by replacing the N by a C in the resource name (eg: XtNactivePage is the name XtNactivePage is the class. The access types are C (resource may be set at create time), S (may be set using XtSetValues), or G (may be read using XtGetValues).

XcgNactivePage: Type = Integer, Default = 1, Access = CSG
Sets the active page. Page numbering begins with 1. The tab of active page is redrawn to appear on top. When the resource autoManage is set, the corresponding manager widget for the page is managed and the previous active manager widget is unmanaged. If the widget is realized, the XcgNnewPageCallback callback is also called. See Section 10 for details.
XcgNautoManage: Type = Boolean, Default = True, Access = CSG
Controls whether TabBook automatically manages the active page's manager widget when the user presses a tab. See Section 10 for details.
XcgNnewPageCallback: Type = Callback Default = None, Access = CSG
The callback invoked when a tab button is pressed. See Section 7.

6. Constraint Resources

TabBook has the following constraint resources that govern how manager children are positioned within their page.

XcgNresizeChild

Type = Integer, Default = XcgRESIZE_NONE, Access = CG
defines whether a manager child is resized. possible values are:

XcgRESIZE_NONE: the child is not resized.
XcgRESIZE_VERTICAL: the child is resized to be the height of the page. Its width is not altered.
XcgRESIZE_HORIZONTAL: the child is resized to be the width of the page. Its height is not altered.
XcgRESIZE_BOTH: the child is resized to be the width and height of the page. This is the recommended setting for a TabBook that is a child of another TabBook.

XcgNanchorChild

Type = Integer, Default = XcgANCHOR_NORTH, Access = CG
Controls the placement of the child manager within the page. Possible values are:

XcgANCHOR_CENTER: The child is centered, horizontally and vertically.
XcgANCHOR_EAST: The child is right aligned and centered vertically.
XcgANCHOR_NORTH: The child is top aligned and centered horizontally.
XcgANCHOR_NORTHEAST: The child is top right aligned.
XcgANCHOR_NORTHWEST: The child is top left aligned.
XcgANCHOR_SOUTH: The child is bottom aligned and centered horizontally.
XcgANCHOR_SOUTHEAST: The child is bottom right aligned.
XcgANCHOR_SOUTHWEST: The child is bottom left aligned.
XcgANCHOR_WEST: The child is left aligned and centered vertically.

7. Callbacks

The XcgNnewPageCallback callback is invoked when the user presses a tab button for a new page. If the user clicks the tab button of the current page, no action is taken at all. The callback is also called when the resource XcgNactivePage changes or optionally on a call of XcgTabBookSetActivePage. Finally, it is called when the TabBook widget is initially managed. In that case, the prev_active_page field is zero.

The callback passes a pointer to the following structure:

typedef struct _XcgTabBookCallbackData
{
	XcgTabBookReasonType reason;	/* reason for callback */
	XEvent *event;			/* button event, NULL if emulated  */
	int prev_active_page;		/* 0 when initially called */
	int active_page;		/* new active page (1,2...) */
	Widget button;			/* the button widget which was
					   pressed (emulated or actual*/
	Boolean ret_veto;		/* caller may set to True to stop page change */
	int future1;
	void * future2;
} XcgTabBookCallbackData;

reason: set to XcgNewPage
event: The XEvent of the button activate, or NULL if the callback was emulated.
prev_active_page: The page number that was previously active, or zero if this is the first time.
active_page: The page number of the newly active page.
button: The push button that was pressed, or NULL if emulated.
ret_veto: initialized to False. If the callback sets to True, then the button press is ignored. No change is made to a new active page.
future: Set to zero

8. Translations

TabBook has no translations.

9. TabBook API

TabBook contains the following functions that control the widget behavior.

9.1 XcgTabBookSetActivePage -- The active page is changed

Function

The active page is changed to the passed page number. Page numbers begin with 1. If this results in a new active page, the effect is as if the user pressed the corresponding tab button. It is also equivalent to setting the resource, XcgNactivePage. However, the NewPage callback that would normally be called under these circumstances can be optionally suppressed. See Section 10 for details.

C-call

Boolean XcgTabBookSetActivePage(Widget w, int page, int option )

Input

w: TabBook widget
page: the page number to activate.
option: bitmapped
XcgTabBook_OPT_NO_CB - don't call NewPage callback

Output

Nothing

Return

True - page has been changed
False - non-existent page number

9.2 XcgTabBookGetActivePage -- The active page is returned

Function

get the active page number

C-call

int XcgTabBookGetActivePage(Widget w)

Input

w: TabBook widget

Output

Nothing

Return

The current active page number (1,2,...)
A zero means the widget has not been managed at least once.

9.3 XcgTabBookGetActivePageWidget -- get the active page's manager widget child

Function

The active page's manager widget child is returned.

C-call

Widget XcgTabBookGetActivePageWidget(Widget w)

Input

w: TabBook widget

Output

Nothing

Return

The manager Widget representing the active page. A NULL means the widget has not been managed at least once.

10. Widget Logic

When the resource autoManage is set, TabBook handles all details of page management. Each child manager widget is forced to be un-managed except for the one corresponding to the active page. When the user presses a tab pushbutton, the old manager is un-managed and the new active page's manager widget is managed so it appears. The order of insertion of child widgets into TabBook determines the correspondence of pushbutton tabs to manager widgets. You may insert all pushbuttons then all manager widgets or you may interleave them. The first pushbutton inserted corresponds to the first manager widget inserted and these constitute page 1.

In order to monitor when the user changes pages, You may add a callback to each tab pushbutton or you can use the XcgNnewPageCallback callback. The latter technique allows you to veto the change in page if, for example, you detect an error.
TabBook Widget