X11 Work Bench Toolkit  1.0
Frame Window APIs and Structures

Data Structures

struct  __WB_FRAME_WINDOW__
 main controlling structure for frame windows More...
 

Macros

#define FRAME_WINDOW_TAG   (*((const unsigned int *)"FWFW"))
 TAG for the WBFrameWindow structure.
 

Typedefs

typedef struct __WB_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

WBFrameWindowFWCreateFrameWindow (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__ WBFrameWindowFWGetFrameWindowStruct (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...
 
WBChildFrameFWGetContainedWindowByIndex (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...
 
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

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

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. You should not manipulate this structure directly. Use the appropriate API functions.

typedef struct __WB_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

Enumeration Type Documentation

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 285 of file frame_window.h.

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 301 of file frame_window.h.

Function Documentation

int FWAddContainedWindow ( WBFrameWindow pFrameWindow,
WBChildFrame pNew 
)

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

Parameters
pFrameWindowA pointer to a WBFrameWindow structure for the frame window
pNewA 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 1255 of file frame_window.c.

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
szTitleA zero-byte terminated ASCII string that defines the window title
idIconAn integer identifier coresponding to a registered icon resource
szMenuResourceA zero-byte terminated ASCII definition of the menu for this window. Pass 'NULL' for this parameter if you do not want a menu.
iXAn integer identifying the x-coordinate for the window, or -1 for default
iYAn integer identifying the y-coordinate for the window, or -1 for default
iWidthAn integer identifying the width of the window, or -1 for default
iHeightAn integer identifying the height of the window, or -1 for default
pUserCallbackA WBWinEvent callback function that receives event notifications for the window
iFlagsAn 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 444 of file frame_window.c.

void FWDestroyFrameWindow ( Window  wID)

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

Parameters
wIDThe 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 684 of file frame_window.c.

void FWDestroyFrameWindow2 ( WBFrameWindow pFrameWindow)

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

Parameters
pFrameWindowThe 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 689 of file frame_window.c.

int FWGetChildFrameIndex ( WBFrameWindow pFrameWindow,
WBChildFrame pCont 
)

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

Parameters
pFrameWindowA pointer to a WBFrameWindow structure for the frame window
pContA 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 1631 of file frame_window.c.

WBChildFrame* FWGetContainedWindowByIndex ( const WBFrameWindow pFrameWindow,
int  iIndex 
)

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

Parameters
pFrameWindowA const pointer to a WBFrameWindow structure for the frame window
iIndexThe '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 1227 of file frame_window.c.

XColor FWGetDefaultBD ( void  )

Get the default border color.

Returns
XColor representing default border color

Header File: frame_window.h

Definition at line 408 of file frame_window.c.

XColor FWGetDefaultBG ( void  )

Get the default background color.

Returns
XColor representing default background color

Header File: frame_window.h

Definition at line 401 of file frame_window.c.

XColor FWGetDefaultFG ( void  )

Get the default foreground color.

Returns
XColor representing default foreground color

Header File: frame_window.h

Definition at line 394 of file frame_window.c.

static __inline__ WBFrameWindow* FWGetFrameWindowStruct ( Window  wID)
static

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

Parameters
wIDA 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 818 of file frame_window.h.

int FWGetNumContWindows ( const WBFrameWindow pFrameWindow)

Returns the total number of 'contained' windows.

Parameters
pFrameWindowA 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 1205 of file frame_window.c.

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

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

Parameters
pFrameWindowA pointer to a WBFrameWindow structure for the frame window
pContA pointer to a WBChildFrame structure for the contained window. Use NULL for the current focus window
iIndexThe 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 -1 moves the tab 1 to the left
A value of -2 moves the tab 1 to the right

Use a value of '0' to move the tab to the beginning.
Returns
void

Header File: frame_window.h

Definition at line 1668 of file frame_window.c.

void FWRecalcLayout ( Window  wID)

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

Parameters
wIDThe 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 1046 of file frame_window.c.

void FWRemoveContainedWindow ( WBFrameWindow pFrameWindow,
WBChildFrame pCont 
)

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

Parameters
pFrameWindowA pointer to a WBFrameWindow structure for the frame window
pContA 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 1321 of file frame_window.c.

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

Replace a 'contained' window from a frame window.

Parameters
pFrameWindowA pointer to a WBFrameWindow structure for the frame window
pContA pointer to the WBChildFrame for the window that is to be removed from the 'contents' for the frame window
pContNewA 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 1434 of file frame_window.c.

void FWSetFocusWindow ( WBFrameWindow pFrameWindow,
WBChildFrame pCont 
)

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

Parameters
pFrameWindowA pointer to a WBFrameWindow structure for the frame window
pContA pointer to the WBChildFrame for the window that is to be assigned the focus.
Returns
void

Header File: frame_window.h

Definition at line 1488 of file frame_window.c.

void FWSetFocusWindowIndex ( WBFrameWindow pFrameWindow,
int  iIndex 
)

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

Parameters
pFrameWindowA pointer to a WBFrameWindow structure for the frame window
iIndexThe 'tab order' index of the 'contained' window that is to receive the focus
Returns
void

Header File: frame_window.h

Definition at line 1519 of file frame_window.c.

void FWSetMenuHandlers ( WBFrameWindow pFrameWindow,
const WBFWMenuHandler pHandlerArray 
)

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

Parameters
pFrameWindowThe pointer to the WBFrameWindow structure for the desired frame window
pHandlerArrayA 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 761 of file frame_window.c.

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

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

Parameters
pFrameWindowA pointer to a WBFrameWindow structure for the frame window
nTabsThe total number of tabs in 'pTabs'. If 'pTabs' is NULL, it is the default (even) tab spacing.
pTabsA 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 1829 of file frame_window.c.

void FWSetStatusText ( WBFrameWindow pFrameWindow,
const char *  szText 
)

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

Parameters
pFrameWindowA pointer to a WBFrameWindow structure for the frame window
szTextA 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 1793 of file frame_window.c.

void FWSetUserCallback ( WBFrameWindow pFW,
WBWinEvent  pCallBack 
)

assign a new WBWinEvent callback function for a frame window

Parameters
pFWA pointer to the WBFrameWindow structure
pCallBackA 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 739 of file frame_window.c.