Frame Window APIs and Structures

Data Structures
struct	tagWB_FRAME_WINDOW
	main controlling structure for frame windows More...

Macros
#define	FRAME_WINDOW_TAG   (*((const unsigned int *)"FWFW"))
	TAG for the WBFrameWindow structure.
#define	MOVE_CHILD_FRAME_TAB_INDEX_BEGINNING   0
	pass as 'iIndex' for FWMoveChildFrameTabIndex() to move the tab index to the beginning
#define	MOVE_CHILD_FRAME_TAB_INDEX_RIGHT   -2
	pass as 'iIndex' for FWMoveChildFrameTabIndex() to move the tab index right
#define	MOVE_CHILD_FRAME_TAB_INDEX_LEFT   -1
	pass as 'iIndex' for FWMoveChildFrameTabIndex() to move the tab index left

Typedefs
typedef struct tagWB_FRAME_WINDOW	WBFrameWindow
	main controlling structure for frame windows More...

Enumerations
enum	WBFrameWindow_FLAGS {   WBFrameWindow_APP_WINDOW = 1,   WBFrameWindow_VISIBLE = 2,   WBFrameWindow_NO_TABS = 4,   WBFrameWindow_STATUS_BAR = 8,   WBFrameWindow_MAX = 0x80000000L }
	Frame Window type and status flags. More...
enum	WBStatusTabInfo_FLAGS {   WBStatusTabInfo_MASK = 0x0fffffff,   WBStatusTabInfo_BREAK = 0x10000000,   WBStatusTabInfo_JUSTIFY_MASK = 0x6fffffff,   WBStatusTabInfo_JUSTIFY_LEFT = 0x00000000,   WBStatusTabInfo_JUSTIFY_CENTER = 0x20000000,   WBStatusTabInfo_JUSTIFY_RIGHT = 0x40000000,   WBStatusTabInfo_JUSTIFY_res6 = 0x60000000,   WBStatusTabInfo_RTL_COLUMN = 0x80000000 }
	enumeration for bit flags that are 'or'd with the tab stop index More...

Functions
WBFrameWindow *	FWCreateFrameWindow (const char *szTitle, int idIcon, const char *szMenuResource, int iX, int iY, int iWidth, int iHeight, WBWinEvent pUserCallback, int iFlags)
	Create a frame window. More...
void	FWRecalcLayout (Window wID)
	Force a frame window to recalculate its layout, which may involve resizing multiple contained windows. More...
void	FWSetUserCallback (WBFrameWindow *pFW, WBWinEvent pCallBack)
	assign a new WBWinEvent callback function for a frame window More...
static __inline__ WBFrameWindow *	FWGetFrameWindowStruct (Window wID)
	Obtain the associated WBFrameWindow structure pointer for a frame window's Window ID. More...
void	FWDestroyFrameWindow (Window wID)
	Function to destroy a frame window based on the Window id. More...
void	FWDestroyFrameWindow2 (WBFrameWindow *pFrameWindow)
	Function to destroy a frame window based on the WBFrameWindow structure. More...
void	FWSetMenuHandlers (WBFrameWindow *pFrameWindow, const WBFWMenuHandler *pHandlerArray)
	Function to assign the default menu handler to a frame window. More...
int	FWGetNumContWindows (const WBFrameWindow *pFrameWindow)
	Returns the total number of 'contained' windows. More...
WBChildFrame *	FWGetContainedWindowByIndex (const WBFrameWindow *pFrameWindow, int iIndex)
	Returns the Window ID for the specified 'contained' window. The index follows the tab order. More...
int	FWAddContainedWindow (WBFrameWindow *pFrameWindow, WBChildFrame *pNew)
	Adds a 'contained' window and returns the tab order index. More...
void	FWRemoveContainedWindow (WBFrameWindow *pFrameWindow, WBChildFrame *pCont)
	Removes a 'contained' window from a frame window. Does not destroy the 'contained' window. More...
void	FWReplaceContainedWindow (WBFrameWindow *pFrameWindow, WBChildFrame *pCont, WBChildFrame *pContNew)
	Replace a 'contained' window from a frame window. More...
void	FWSetFocusWindow (WBFrameWindow *pFrameWindow, WBChildFrame *pCont)
	Sets the focus to a specific contained window using the Window ID. More...
void	FWSetFocusWindowIndex (WBFrameWindow *pFrameWindow, int iIndex)
	Sets the focus to a specific contained window using its tab order index. More...
int	FWGetChildFrameIndex (WBFrameWindow *pFrameWindow, WBChildFrame *pCont)
	Sets the focus to a specific contained window using its tab order index. More...
void	FWMoveChildFrameTabIndex (WBFrameWindow *pFrameWindow, WBChildFrame *pCont, int iIndex)
	Sets the specific contained window to a particular index in the tab order. More...
void	FWSetStatusText (WBFrameWindow *pFrameWindow, const char *szText)
	Sets the 'status' text for a Frame Window with a status bar, forcing a re-paint. More...
void	FWSetStatusTabInfo (WBFrameWindow *pFrameWindow, int nTabs, const int *pTabs)
	Sets the 'status' tab info for a Frame Window with a status bar. More...
XColor	FWGetDefaultFG (void)
	Get the default foreground color. More...
XColor	FWGetDefaultBG (void)
	Get the default background color. More...
XColor	FWGetDefaultBD (void)
	Get the default border color. More...
WB_FONTC	FWGetFont (WBFrameWindow *pFW)
	Get the frame window WB_FONTC. More...
WB_FONTC	FWGetBoldFont (WBFrameWindow *pFW)
	Get the frame window bold WB_FONTC. More...
Atom	aTAB_MESSAGE
	command sent by Client Message related to 'tab' operations

Detailed Description

To create a frame window, you will need to call the FWCreateFrameWindow() API function, which returns a WBFrameWindow structure pointer. Until the window has been destroyed this pointer will remain valid, though you should not manipulate its contents directly.
Typical code for creating a frame window follows:

XSizeHints  xsh;            // Size hints for window manager
WBFrameWindow *pFrame;      // pointer to WBFrameWindow for my new frame window

...

  // use 'size hints' along with display characteristics to pre-size window

  WBInitSizeHints(&xsh,                  // pointer to XSizeHints
                  WBGetDefaultDisplay(), // current (default) display
                  300,                   // minimum height (300 pixels in this case)
                  600);                  // minimum width (600 pixels in this case)

  // create frame window object

  pFrame = FWCreateFrameWindow("Window Title",           // title
                               ID_APPLICATION,           // 'well known' icon identifier
                                                         // see PXM_GetIconPixmap()
                               szAppMenu,                // default app menu (as text)
                               xsh.x, xsh.y,             // position
                               xsh.width, xsh.height,    // size
                               MyWindowCallback,         // callback
                               WBFrameWindow_APP_WINDOW  // flags and attributes
                               | WBFrameWindow_VISIBLE);

Once the window has been created, you can manage its contents using FWAddContainedWindow() and related functions.
Contained windows need no special interface handling unless you want to control the context of the menu, or overload the frame window's default menu event handling. A set of messages are used by the frame window for its 'contents' windows in order to request that a new menu be assigned to the containing frame window. Menu commands are passed directly to the contained window's callback functions as they are received, before being handled by the frame window itself. In this way the frame window can handle anything NOT already handled by the contained window.
Menu and UI events for which there is no handler should always return '-1'.
In order to 'fit' a contained window within the frame window's client area, it will always be re-sized when added, and whenever it gains the focus. A re-size will also be performed for the 'focus' window whenever the frame window is re-sized. The focus window will need to respond to re-size events and re-draw itself as needed.

Typedef Documentation

WBFrameWindow

WBFrameWindow

main controlling structure for frame windows

By default a frame window can handle multiple documents. Documents are selected via tabs. At least one tab will always be visible unless there are no 'contents'. The contained windows will be re-sized automatically as needed. Contained windows may also register their own menus and/or menu handlers.

The WBFrameWindow structure maintains the basic window state information, and contains additional data members that are not declared in WBFrameWindow. You should not create any derived 'superclass' versions that contain this structure as an embedded member. Instead, you should use a pointer to a WBFrameWindow structure within your implementation, and not rely on any data members within the structure that are not accessible through the use of an API function.

This structure is created using FWCreateFrameWindow(), and destroyed using either FWDestroyFrameWindow() (using the Window ID) or FWDestroyFrameWindow2() (using the structure pointer).

typedef struct tagWB_FRAME_WINDOW
{
  unsigned int ulTag;                  // tag indicating I'm a frame window
  Window wID;                          // Window id for the frame window
  int iFlags;                          // bitmask of attribute flags (see \ref WBFrameWindow_FLAGS enumeration)

  int iClientX;                        // The current X position of the frame window's client area
  int iClientY;                        // The current Y position of the frame window's client area
  int iClientWidth;                    // The current width of the frame window's client area
  int iClientHeight;                   // The current height of the frame window's client area

} WBFrameWindow;

See also

Frame Window APIs and Structures

Definition at line 111 of file X11workbench.h.

Enumeration Type Documentation

WBFrameWindow_FLAGS

enum WBFrameWindow_FLAGS

Frame Window type and status flags.

Assign zero or more of these flags to the 'iFlags' parameter in the call to FWCreateFrameWindow()

Enumerator
WBFrameWindow_APP_WINDOW	set this flag for application top-level window and whenever it is destroyed the application will exit
WBFrameWindow_VISIBLE	set this to make window immediately visible
WBFrameWindow_NO_TABS	set this to disable tabs (single child frame only)
WBFrameWindow_STATUS_BAR	set this to enable a 'status bar' at the bottom
WBFrameWindow_MAX	maximum flag value (for reference only)

Definition at line 295 of file frame_window.h.

WBStatusTabInfo_FLAGS

enum WBStatusTabInfo_FLAGS

enumeration for bit flags that are 'or'd with the tab stop index

Enumerator
WBStatusTabInfo_MASK	mask for the actual tab value
WBStatusTabInfo_BREAK	represents a 'break' (marks end of a column)
WBStatusTabInfo_JUSTIFY_MASK	mask for the 'justification' value
WBStatusTabInfo_JUSTIFY_LEFT	left-justify text within the column (default)
WBStatusTabInfo_JUSTIFY_CENTER	center text within the column
WBStatusTabInfo_JUSTIFY_RIGHT	right justify text within the column
WBStatusTabInfo_JUSTIFY_res6	reserved: unspecified new justification method
WBStatusTabInfo_RTL_COLUMN	bit flag to 'right justify' the column location

Definition at line 311 of file frame_window.h.

Function Documentation

FWAddContainedWindow()

int FWAddContainedWindow	(	WBFrameWindow *	pFrameWindow,
		WBChildFrame *	pNew
	)

Adds a 'contained' window and returns the tab order index.

Parameters

pFrameWindow	A pointer to a WBFrameWindow structure for the frame window
pNew	A pointer to the WBChildFrame for the window that is to become part of the 'contents' for the frame window

Returns

The tab order index of the window, or -1 on error

Header File: frame_window.h

Definition at line 1335 of file frame_window.c.

FWCreateFrameWindow()

WBFrameWindow* FWCreateFrameWindow	(	const char *	szTitle,
		int	idIcon,
		const char *	szMenuResource,
		int	iX,
		int	iY,
		int	iWidth,
		int	iHeight,
		WBWinEvent	pUserCallback,
		int	iFlags
	)

Create a frame window.

Parameters

szTitle	A zero-byte terminated ASCII string that defines the window title
idIcon	An integer identifier coresponding to a registered icon resource
szMenuResource	A zero-byte terminated ASCII definition of the menu for this window. Pass 'NULL' for this parameter if you do not want a menu.
iX	An integer identifying the x-coordinate for the window, or -1 for default
iY	An integer identifying the y-coordinate for the window, or -1 for default
iWidth	An integer identifying the width of the window, or -1 for default
iHeight	An integer identifying the height of the window, or -1 for default
pUserCallback	A WBWinEvent callback function that receives event notifications for the window
iFlags	An integer with one or more bit flags that alters the parameters for the frame window. See WBFrameWindow_FLAGS

Returns

A pointer to a WBFrameWindow object. The caller should not destroy this object, nor directly reference it after the window has been destroyed.

Use this function to create a basic frame window. A frame window has a title, icon, menu, and can contain one or more 'Child Frames'. The menu is optional, and support for multiple 'tab' child frames is also optional, depending on the bit flags set in 'iFlags'.

NOTE: scroll up to the 'Detailed Description' section for an example of how to use this function

Header File: frame_window.h

See also

Frame Window Menu Handling

Definition at line 508 of file frame_window.c.

FWDestroyFrameWindow()

void FWDestroyFrameWindow

(

Window

wID

)

Function to destroy a frame window based on the Window id.

Parameters

wID	The Window ID associated with the WBFrameWindow to destroy

Use this function to destroy a WBFrameWindow based on it's ID. After calling this function the WBFrameWindow struct is no longer valid

Header File: frame_window.h

Definition at line 744 of file frame_window.c.

FWDestroyFrameWindow2()

void FWDestroyFrameWindow2

(

WBFrameWindow *

pFrameWindow

)

Function to destroy a frame window based on the WBFrameWindow structure.

Parameters

pFrameWindow

The pointer to the WBFrameWindow structure for the desired frame window

Use this function to destroy a WBFrameWindow based on the WBFrameWindow struct pointer value. After calling this function the WBFrameWindow struct is no longer valid

Header File: frame_window.h

Definition at line 749 of file frame_window.c.

FWGetBoldFont()

WB_FONTC FWGetBoldFont

(

WBFrameWindow *

pFW

)

Get the frame window bold WB_FONTC.

Returns

WB_FONTC assigned to frame window for bold font

Header File: frame_window.h

Definition at line 462 of file frame_window.c.

FWGetChildFrameIndex()

int FWGetChildFrameIndex	(	WBFrameWindow *	pFrameWindow,
		WBChildFrame *	pCont
	)

Sets the focus to a specific contained window using its tab order index.

Parameters

pFrameWindow	A pointer to a WBFrameWindow structure for the frame window
pCont	A pointer to a WBChildFrame structure for the contained window. Use NULL for the current focus window

Returns

The tab order index of 'pCont', or a negative value on error.

Header File: frame_window.h

Definition at line 1711 of file frame_window.c.

FWGetContainedWindowByIndex()

WBChildFrame* FWGetContainedWindowByIndex	(	const WBFrameWindow *	pFrameWindow,
		int	iIndex
	)

Returns the Window ID for the specified 'contained' window. The index follows the tab order.

Parameters

pFrameWindow	A const pointer to a WBFrameWindow structure for the frame window
iIndex	The 'tab order' index of the 'contained' window. The first window is '0'. A negative value implies the 'current focus' window

Returns

A pointer to the WBChildFrame for the 'contained' window corresponding to the index, or 'NULL' on error

Use this function to get the Window ID of a 'contained' (child frame) window. To get more information about contained 'Child Frame' window, see Child Frames

Header File: frame_window.h

Definition at line 1288 of file frame_window.c.

FWGetDefaultBD()

XColor FWGetDefaultBD

(

void

)

Get the default border color.

Returns

XColor representing default border color

Header File: frame_window.h

Definition at line 438 of file frame_window.c.

FWGetDefaultBG()

XColor FWGetDefaultBG

(

void

)

Get the default background color.

Returns

XColor representing default background color

Header File: frame_window.h

Definition at line 431 of file frame_window.c.

FWGetDefaultFG()

XColor FWGetDefaultFG

(

void

)

Get the default foreground color.

Returns

XColor representing default foreground color

Header File: frame_window.h

Definition at line 424 of file frame_window.c.

FWGetFont()

WB_FONTC FWGetFont

(

WBFrameWindow *

pFW

)

Get the frame window WB_FONTC.

Returns

WB_FONTC assigned to frame window for font

Header File: frame_window.h

Definition at line 445 of file frame_window.c.

FWGetFrameWindowStruct()

static __inline__ WBFrameWindow* FWGetFrameWindowStruct ( Window  wID )

static

Obtain the associated WBFrameWindow structure pointer for a frame window's Window ID.

Parameters

wID	A valid Window ID

Returns

A pointer to the associated WBFrameWindow structure (if it is a WBFrameWindow), or NULL on error

Use this function to safely obtain the correct WBFrameWindow structure for a given Window ID.

Header File: frame_window.h

Definition at line 835 of file frame_window.h.

FWGetNumContWindows()

int FWGetNumContWindows

(

const WBFrameWindow *

pFrameWindow

)

Returns the total number of 'contained' windows.

Parameters

pFrameWindow

A const pointer to a WBFrameWindow structure for the frame window

Returns

The total number of 'contained' windows, or -1 on error

Header File: frame_window.h

Definition at line 1266 of file frame_window.c.

FWMoveChildFrameTabIndex()

void FWMoveChildFrameTabIndex	(	WBFrameWindow *	pFrameWindow,
		WBChildFrame *	pCont,
		int	iIndex
	)

Sets the specific contained window to a particular index in the tab order.

Parameters

pFrameWindow	A pointer to a WBFrameWindow structure for the frame window
pCont	A pointer to a WBChildFrame structure for the contained window. Use NULL for the current focus window
iIndex	The new 'tab order' index to assign to the 'contained' window, or a constant indicating how to adjust the index A value of 0 to n assigns the specified tab index. Positive values greater than the total number of tabs moves it to the end of the tab order. A value of MOVE_CHILD_FRAME_TAB_INDEX_LEFT moves the tab 1 to the left A value of MOVE_CHILD_FRAME_TAB_INDEX_RIGHT moves the tab 1 to the right Use a value of MOVE_CHILD_FRAME_TAB_INDEX_BEGINNING (0) to move the tab to the beginning.

Returns

void

Header File: frame_window.h

Definition at line 1748 of file frame_window.c.

FWRecalcLayout()

void FWRecalcLayout

(

Window

wID

)

Force a frame window to recalculate its layout, which may involve resizing multiple contained windows.

Parameters

wID	The Window ID of the WBFrameWindow (typically will be called within a message handler, such as a window re-size)

Forces the frame window to recalculate its layout (i.e. size of menus, tabs, and 'child frame' windows) and propogate that information to all 'owned' windows and objects it contains.

Header File: frame_window.h

Definition at line 1107 of file frame_window.c.

FWRemoveContainedWindow()

void FWRemoveContainedWindow	(	WBFrameWindow *	pFrameWindow,
		WBChildFrame *	pCont
	)

Removes a 'contained' window from a frame window. Does not destroy the 'contained' window.

Parameters

pFrameWindow	A pointer to a WBFrameWindow structure for the frame window
pCont	A pointer to the WBChildFrame for the window that is to be removed from the 'contents' for the frame window

Returns

void

Header File: frame_window.h

Definition at line 1401 of file frame_window.c.

FWReplaceContainedWindow()

void FWReplaceContainedWindow	(	WBFrameWindow *	pFrameWindow,
		WBChildFrame *	pCont,
		WBChildFrame *	pContNew
	)

Replace a 'contained' window from a frame window.

Parameters

pFrameWindow	A pointer to a WBFrameWindow structure for the frame window
pCont	A pointer to the WBChildFrame for the window that is to be removed from the 'contents' for the frame window
pContNew	A pointer to the WBChildFrame for the window that is to replace the previous contained window

Returns

void

sometimes the document type will change when you are editing or creating a new document. As an example, you are creating a plain text file, but then name it with a '.c' extension, or with the name 'Makefile'. Your document editing window might decide to change the view based on that information, and you would then re-open the file with the new document editing window, and replace the current one with that one, then destroy the old one (after saving the new document, of course). This provides a seamless way of making all of this happen without the user noticing anything EXCEPT the new view.

An alternate purpose might be to view something in 'text mode' or 'graphic edit mode'. A dialog resource or image resource editor might be a typical use for this. In 'text mode' you view the resource as a text file (it might be a pixmap, for example). Switching to 'graphic edit mode' could display a graphical editor for the pixmap, which would allow you to draw, erase, add elements, change colors, etc. like any other graphical editor might do.

Typically you'll have a default view for 'any document type'. The application would need to swap it out for the correct view when the document type changes, by creating the new document view/edit window, and then calling this function.

Header File: frame_window.h

Definition at line 1514 of file frame_window.c.

FWSetFocusWindow()

void FWSetFocusWindow	(	WBFrameWindow *	pFrameWindow,
		WBChildFrame *	pCont
	)

Sets the focus to a specific contained window using the Window ID.

Parameters

pFrameWindow	A pointer to a WBFrameWindow structure for the frame window
pCont	A pointer to the WBChildFrame for the window that is to be assigned the focus.

Returns

void

Header File: frame_window.h

Definition at line 1568 of file frame_window.c.

FWSetFocusWindowIndex()

void FWSetFocusWindowIndex	(	WBFrameWindow *	pFrameWindow,
		int	iIndex
	)

Sets the focus to a specific contained window using its tab order index.

Parameters

pFrameWindow	A pointer to a WBFrameWindow structure for the frame window
iIndex	The 'tab order' index of the 'contained' window that is to receive the focus

Returns

void

Header File: frame_window.h

Definition at line 1599 of file frame_window.c.

FWSetMenuHandlers()

void FWSetMenuHandlers	(	WBFrameWindow *	pFrameWindow,
		const WBFWMenuHandler *	pHandlerArray
	)

Function to assign the default menu handler to a frame window.

Parameters

pFrameWindow	The pointer to the WBFrameWindow structure for the desired frame window
pHandlerArray	A pointer to an array of WBFWMenuHandler structures - see FW_MENU_HANDLER_ENTRY

Assigns the menu handlers for the frame window. The array will be copied, and the copy will be used internally. These handlers are checked for matching entries after checking the 'contained' window's handlers for the WBChildFrame that has the current focus.

See also

Frame Menus

Header File: frame_window.h

Definition at line 821 of file frame_window.c.

FWSetStatusTabInfo()

void FWSetStatusTabInfo	(	WBFrameWindow *	pFrameWindow,
		int	nTabs,
		const int *	pTabs
	)

Sets the 'status' tab info for a Frame Window with a status bar.

Parameters

pFrameWindow	A pointer to a WBFrameWindow structure for the frame window
nTabs	The total number of tabs in 'pTabs'. If 'pTabs' is NULL, it is the default (even) tab spacing.
pTabs	A pointer to an array of integers containing tab values. See below on how they are interpreted.

Returns

void

Use this function to assign the tab spacing and/or columns for the status bar. Tabs are bit-wise 'or'd with flags from the WBStatusTabInfo_FLAGS enumeration.
The physical tab value starts at the left side unless WBStatusTabInfo_RTL_COLUMN has been 'or'd with its value. Columns width is determined by both the next tab value and the current one. Use the 'WBStatusTabInfo_BREAK' flag to create a 'blank' area that defines the width of the previous column but does not have anything displayed within it.
To left, right, or center text within a column, use one of the WBStatusTabInfo_JUSTIFY_ constants. The default (zero) is left-justification (even for RTL columns).
This function does NOT force a re-paint of the status bar. It does invalidate the status bar rectangle, however. To force a re-paint after updating the tabs, call WBUpdateWindow() for the frame window.

Header File: frame_window.h

Definition at line 1909 of file frame_window.c.

FWSetStatusText()

void FWSetStatusText	(	WBFrameWindow *	pFrameWindow,
		const char *	szText
	)

Sets the 'status' text for a Frame Window with a status bar, forcing a re-paint.

Parameters

pFrameWindow	A pointer to a WBFrameWindow structure for the frame window
szText	A tab-delimited character string containing UTF8 or ASCII status text. A copy of this will be stored internally.

Returns

void

Use this function to update the status text. Status text can contain multiple 'columns' that are displayed using the tab stop information assigned by FWSetStatusTabInfo(). Each column's text data will be 'appropriately justified' and displayed in the status bar according to the tab info.
This function forces a re-paint of the status bar. If you also want to change the tabs, call FWSetStatusTabInfo() first, followed by this function.

Header File: frame_window.h

Definition at line 1873 of file frame_window.c.

FWSetUserCallback()

void FWSetUserCallback	(	WBFrameWindow *	pFW,
		WBWinEvent	pCallBack
	)

assign a new WBWinEvent callback function for a frame window

Parameters

pFW	A pointer to the WBFrameWindow structure
pCallBack	A function pointer of type WBWinEvent for the user-defined event handler callback. Can be NULL.

Use this function to assign the event handler callback for the frame window. Not all events pass through the callback. Some events are sent directly to the callback, and may have required implementation.

Header File: frame_window.h

Definition at line 799 of file frame_window.c.