X11 Work Bench Toolkit  1.0
Child frame Window API

Data Structures

struct  __WBChildFrame__
 Structure that defines a Child Frame within a Frame Window. More...
 
struct  __WBChildFrameUI__
 Structure that defines a Child Frame's UI, mainly for a 'superclass'. More...
 

Macros

#define CHILD_FRAME_TAG   (*((const unsigned int * const)"FWCF"))
 TAG for the WBChildFrame structure.
 
#define CHILD_FRAME_UI_TAG   ((WB_UINT32)'F' | ((WB_UINT32)'W' << 8) | ((WB_UINT32)'C' << 16) | ((WB_UINT32)'U' << 24)) /* FWCU */
 TAG for the WBChildFrameUI structure.
 
#define EDIT_WINDOW_TAG   (*((const unsigned int * const)"FWEW"))
 TAG for the WBEditWindow structure.
 

Typedefs

typedef struct __WBChildFrame__ WBChildFrame
 Structure that defines a Child Frame within a Frame Window. More...
 
typedef struct __WBChildFrameUI__ WBChildFrameUI
 Structure that defines a Child Frame's UI, mainly for a 'superclass'. More...
 

Enumerations

enum  WBChildFrame_FLAGS {
  WBChildFrame_NO_TAB = 1, WBChildFrame_PIXELS = 2, WBChildFrame_VSPLIT = 4, WBChildFrame_HSPLIT = 8,
  WBChildFrame_SPLIT_MASK = 12, WBChildFrame_SPLIT_NOSIZE = 16
}
 enumeration for 'fFlags' member of WBChildFrame More...
 

Functions

int FWInitChildFrame (WBChildFrame *pChildFrame, WBFrameWindow *pOwner, XFontSet rFontSet, const char *szFocusMenu, const WBFWMenuHandler *pHandlerArray, WBWinEvent pUserCallback, int fFlags)
 Initialize a child frame (assumed to be a base 'class' for the window) More...
 
void FWDestroyChildFrame (WBChildFrame *pChildFrame)
 Destroy an Child Frame. More...
 
void FWSetChildFrameMenu (WBChildFrame *pChildFrame, const char *szFocusMenu)
 Function to assign the menu resource to a Child Frame. More...
 
void FWSetChildFrameMenuHandlers (WBChildFrame *pChildFrame, const WBFWMenuHandler *pHandlerArray)
 Function to assign menu handlers to a Child Frame. More...
 
void FWSetChildFrameDisplayName (WBChildFrame *pChildFrame, const char *szDisplayName)
 Assign the display name. More...
 
void FWSetChildFrameImageAtom (WBChildFrame *pChildFrame, Atom aImage)
 Assign the image atom for the child frame. the image appears in the tab associated with the child frame. More...
 
void FWSetChildFrameExtent (WBChildFrame *pChildFrame, int iXExtent, int iYExtent)
 Set the X,Y extent for the child frame (notifies everything) More...
 
void FWSetChildFrameScrollInfo (WBChildFrame *pChildFrame, int iRow, int iMaxRow, int iCol, int iMaxCol, int iRowHeight, int iColWidth)
 Set the X,Y extent for the child frame (notifies everything) More...
 
void FWChildFrameRecalcLayout (WBChildFrame *pChildFrame)
 Child frame notification callback (called by frame window) More...
 
void FWChildFrameStatusChanged (WBChildFrame *pChildFrame)
 Notify Child Frame to update status text in Frame Window. More...
 
int FWChildFrameQueryClose (WBChildFrame *pChildFrame)
 Returns if it's safe to close the child frame; prompts user as needed. More...
 
int FWChildFrameEvent (Window wID, XEvent *pEvent)
 Default event handler for Child Frame window. More...
 
static __inline__ WBChildFrameFWGetChildFrameStruct (Window wID)
 Obtain the associated WBChildFrame structure pointer for a Window ID. More...
 
#define FW_FILE_NEW_MENU   "IDM_FILE_NEW"
 
#define FW_FILE_CLOSE_MENU   "IDM_FILE_CLOSE"
 
#define FW_FILE_OPEN_MENU   "IDM_FILE_OPEN"
 
#define FW_FILE_SAVE_MENU   "IDM_FILE_SAVE"
 
#define FW_FILE_SAVE_AS_MENU   "IDM_FILE_SAVE_AS"
 
#define FW_FILE_SAVE_ALL_MENU   "IDM_FILE_SAVE_ALL"
 
#define FW_EDIT_CUT_MENU   "IDM_EDIT_CUT"
 
#define FW_EDIT_COPY_MENU   "IDM_EDIT_COPY"
 
#define FW_EDIT_PASTE_MENU   "IDM_EDIT_PASTE"
 
#define FW_EDIT_DELETE_MENU   "IDM_EDIT_DELETE"
 
#define FW_EDIT_SELECT_ALL_MENU   "IDM_EDIT_SELECT_ALL"
 
#define FW_EDIT_SELECT_NONE_MENU   "IDM_EDIT_SELECT_NONE"
 
#define FW_FILE_NEW_ACCEL   "Ctrl+N"
 
#define FW_FILE_CLOSE_ACCEL   "Ctrl+F4"
 
#define FW_FILE_OPEN_ACCEL   "Ctrl+O"
 
#define FW_FILE_SAVE_ACCEL   "Ctrl+S"
 
#define FW_FILE_SAVE_AS_ACCEL   "Ctrl+Shift+S"
 
#define FW_FILE_SAVE_ALL_ACCEL   "Ctrl+Shift+L"
 
#define FW_EDIT_CUT_ACCEL   "Ctrl+X"
 
#define FW_EDIT_COPY_ACCEL   "Ctrl+C"
 
#define FW_EDIT_PASTE_ACCEL   "Ctrl+V"
 
#define FW_EDIT_SELECT_ALL_ACCEL   "Ctrl+A"
 
#define FW_EDIT_SELECT_NONE_ACCEL   "Ctrl+Shift+A"
 

Detailed Description

The 'Child Frame' API for the X11workbench Toolkit identifies those functions that implement 'Child Frame' windows. A Child Frame window is a child window that is registered with the containing frame window and typically displays a tab on the frame window for easy access. It also has its own menu and menu handlers. Typically another window type will 'derive' from this.

See Also
Edit Window APIs and Structures

Macro Definition Documentation

#define FW_EDIT_COPY_ACCEL   "Ctrl+C"

standard menu accelerator key for 'Edit Copy' functionality

Definition at line 127 of file child_frame.h.

#define FW_EDIT_COPY_MENU   "IDM_EDIT_COPY"

standard menu item identifier for 'Edit Copy' functionality

Definition at line 113 of file child_frame.h.

#define FW_EDIT_CUT_ACCEL   "Ctrl+X"

standard menu accelerator key for 'Edit Cut' functionality

Definition at line 126 of file child_frame.h.

#define FW_EDIT_CUT_MENU   "IDM_EDIT_CUT"

standard menu item identifier for 'Edit Cut' functionality

Definition at line 112 of file child_frame.h.

#define FW_EDIT_DELETE_MENU   "IDM_EDIT_DELETE"

standard menu item identifier for 'Edit Delete' functionality

Definition at line 115 of file child_frame.h.

#define FW_EDIT_PASTE_ACCEL   "Ctrl+V"

standard menu accelerator key for 'Edit Paste' functionality

Definition at line 128 of file child_frame.h.

#define FW_EDIT_PASTE_MENU   "IDM_EDIT_PASTE"

standard menu item identifier for 'Edit Paste' functionality

Definition at line 114 of file child_frame.h.

#define FW_EDIT_SELECT_ALL_ACCEL   "Ctrl+A"

standard menu item identifier for 'Edit Select All' functionality

Definition at line 129 of file child_frame.h.

#define FW_EDIT_SELECT_ALL_MENU   "IDM_EDIT_SELECT_ALL"

standard menu item identifier for 'Edit Select All' functionality

Definition at line 116 of file child_frame.h.

#define FW_EDIT_SELECT_NONE_ACCEL   "Ctrl+Shift+A"

standard menu item identifier for 'Edit Select None' functionality

Definition at line 130 of file child_frame.h.

#define FW_EDIT_SELECT_NONE_MENU   "IDM_EDIT_SELECT_NONE"

standard menu item identifier for 'Edit Select None' functionality

Definition at line 117 of file child_frame.h.

#define FW_FILE_CLOSE_ACCEL   "Ctrl+F4"

standard menu accelerator key for 'File Close' functionality

Definition at line 120 of file child_frame.h.

#define FW_FILE_CLOSE_MENU   "IDM_FILE_CLOSE"

standard menu item identifier for 'File Close' functionality

Definition at line 106 of file child_frame.h.

#define FW_FILE_NEW_ACCEL   "Ctrl+N"

standard menu accelerator key for 'File New' functionality

Definition at line 119 of file child_frame.h.

#define FW_FILE_NEW_MENU   "IDM_FILE_NEW"

standard menu item identifier for 'File New' functionality

Definition at line 105 of file child_frame.h.

#define FW_FILE_OPEN_ACCEL   "Ctrl+O"

standard menu accelerator key for 'File Open' functionality

Definition at line 121 of file child_frame.h.

#define FW_FILE_OPEN_MENU   "IDM_FILE_OPEN"

standard menu item identifier for 'File Open' functionality

Definition at line 107 of file child_frame.h.

#define FW_FILE_SAVE_ACCEL   "Ctrl+S"

standard menu accelerator key for 'File Save' functionality

Definition at line 122 of file child_frame.h.

#define FW_FILE_SAVE_ALL_ACCEL   "Ctrl+Shift+L"

standard menu accelerator key for 'File Save All' functionality

Definition at line 124 of file child_frame.h.

#define FW_FILE_SAVE_ALL_MENU   "IDM_FILE_SAVE_ALL"

standard menu item identifier for 'File Save All' functionality

Definition at line 110 of file child_frame.h.

#define FW_FILE_SAVE_AS_ACCEL   "Ctrl+Shift+S"

standard menu accelerator key for 'File Save As' functionality

Definition at line 123 of file child_frame.h.

#define FW_FILE_SAVE_AS_MENU   "IDM_FILE_SAVE_AS"

standard menu item identifier for 'File Save As' functionality

Definition at line 109 of file child_frame.h.

#define FW_FILE_SAVE_MENU   "IDM_FILE_SAVE"

standard menu item identifier for 'File Save' functionality

Definition at line 108 of file child_frame.h.

Typedef Documentation

Structure that defines a Child Frame within a Frame Window.

The WBFWMenuHandler structure is designed to be initialized via macros, so that a set of callback functions can then be easily used to handle menu events. If no menu handler is present for a menu item, or if the menu UI handler is NOT NULL and returns a non-zero value, the menu item will be disabled and displayed accordingly. It will not be possible to use its hotkey nor select it. Otherwise, the menu will be displayed normally and be selectable, and its hotkey will be able to activate it.

typedef struct __WBChildFrame__
{
unsigned int ulTag;
// tag indicating I'm a 'Child Frame' window
Window wID;
// window identifier for the 'Child Frame' window. may contain 'None' while being destroyed
// a pointer to the WBFrameWindow owner
XFontSet rFontSet;
// default font set for the window
// client-area geometry (excludes scroll bars)
int iTop;
// 0-based position of the top of the current viewport (in lines or pixels)
int iHeight;
// 0-based height of the current viewport (in lines or pixels)
int iLeft;
// 0-based position of the left of the current viewport (in characters or pixels)
int iWidth;
// 0-based width of the current viewport (in characters or pixels)
int iXExtent;
// cached X extent for the display surface (determines scrolling behavior)
int iYExtent;
// cached Y extent for the display surface (determines scrolling behavior)
// 'scroll info' (horizontal and vertical min/max/pos and other details)
int iSplit;
// reserved - position for 'split' (-1 for 'no split')
// 'scroll info' for 'split' area (implementation-defined)
int fFlags;
// various bitflags defining features.
// display name shown in tab and title bar. You should not alter this member directly.
Atom aImageAtom;
// 'image' atom for display in tabs. default is 'None'. You should not alter this member directly.
char *szStatusText;
// Status text ('WBAlloc'd) to display when this child frame window has the input focus.
// Updated by 'superclass'. Can be NULL.
// WBAlloc'd resource string for this child frame's menu (NULL = 'use default')
// WBAlloc'd menu handler for this child frame's menu (NULL = 'use default')
// message callback function pointer (can be NULL)
void (*destructor)(struct __WBChildFrame__ *);
// pointer to a destructor. if not NULL, will be called by FWDestroyChildFrame()
// pointer to 'WBChildFrameUI' function pointer table (assigned by 'superclass')
// 'Next Object' pointer in an internally stored linked list (do not alter or use this)
See Also
Frame Windows

NOTE: you should not attempt to modify any of these structure members directly. Use the appropriate API functions to modify their values. If this were C++, these members would be marked 'protected'.

Structure that defines a Child Frame's UI, mainly for a 'superclass'.

The base user interface for a child frame does very little except interact with tabs and the Frame Window. To make it really do something, you need some kind of interface. This function table defines the UI interface for a Child Frame that will allow it to perform basic editing and navigation functions. If you need additional capabilities, you can hook the messages with the assigned callback function. Otherwise, most of the work will already be done for your custom child frame.

typedef struct __WBChildFrameUI__
{
unsigned int ulTag;
// tag indicating I'm a 'Child Frame UI' structure
void (*do_char)(WBChildFrame *, XClientMessageEvent *);
// handler for regular WM_CHAR Client Messages (typed-in characters).
// NOT called for 'special' characters.
void (*scancode)(WBChildFrame *, XClientMessageEvent *);
// handler for 'other scan code' WM_CHAR Client Messages (typed-in characters)
void (*bkspace)(WBChildFrame *, int iACS);
// 'backspace' delete character (backspace equivalent).
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*del)(WBChildFrame *, int iACS);
// 'delete' char under cursor (delete equivalent).
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*tab)(WBChildFrame *, int iACS);
// 'tab' char, or tab navigation.
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*enter)(WBChildFrame *, int iACS);
// 'enter' char, or 'enter' for navigation.
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*uparrow)(WBChildFrame *, int iACS);
// 'up' arrow navigation.
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*downarrow)(WBChildFrame *, int iACS);
// 'down' arrow navigation.
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*leftarrow)(WBChildFrame *, int iACS);
// 'left' arrow navigation.
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*rightarrow)(WBChildFrame *, int iACS);
// 'right' arrow navigation.
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*home)(WBChildFrame *, int iACS);
// 'home' arrow navigation.
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*end)(WBChildFrame *, int iACS);
// 'end' arrow navigation.
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*pgup)(WBChildFrame *, int iACS);
// 'page up' navigation.
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*pgdown)(WBChildFrame *, int iACS);
// 'page down' navigation.
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*pgleft)(WBChildFrame *, int iACS);
// 'page left' navigation.
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*pgright)(WBChildFrame *, int iACS);
// 'page right' navigation.
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*help)(WBChildFrame *, int iACS);
// 'help' context (F1).
// 'iACS' is the Alt/Ctrl/Shift flags. See Also: aWM_CHAR
void (*hover_notify)(WBChildFrame *, int x, int y);
// 'mouse hover' notification (x and y are pixel coords with respect to upper left corner)
// 'mouse hover' cancel notification (cancel any 'hover' action)
// returns non-zero if in 'insert' mode, 0 for 'overwrite'
// toggles insert mode on/off (press 'INS' key)
// copy selection to clipboard
// paste from clipboard
void (*cut_to_cb)(WBChildFrame *);
// delete selection, copying to clipboard first
// delete selection only
// select all
// select none
void (*save)(WBChildFrame *, const char *szFileName);
// save to specified file name (NULL to keep same file name)
// get (const) pointer to file name string
void (*mouse_click)(WBChildFrame *, int iX, int iY,
int iButtonMask, int iACS);
// 'mouse click' notification. See Also: aWM_POINTER
void (*mouse_dblclick)(WBChildFrame *, int iX, int iY,
int iButtonMask, int iACS);
// 'mouse double click' notification. See Also: aWM_POINTER
void (*mouse_drag)(WBChildFrame *, int iX, int iY,
int iButtonMask, int iACS);
// 'mouse drag' (begin) notification. See Also: aWM_POINTER
void (*mouse_drop)(WBChildFrame *, int iX, int iY,
int iButtonMask, int iACS);
// 'mouse drop' (drag end) notification. See Also: aWM_POINTER
void (*mouse_move)(WBChildFrame *, int iX, int iY);
// 'mouse motion' notification. See Also: aWM_POINTER
void (*mouse_scrollup)(WBChildFrame *, int iX, int iY,
int iButtonMask, int iACS);
// 'mouse scroll up' notification. See Also: aWM_POINTER
void (*mouse_scrolldown)(WBChildFrame *, int iX, int iY,
int iButtonMask, int iACS);
// 'mouse scroll down' notification. See Also: aWM_POINTER
// 'mouse cancel' notification (cancel 'drag', etc.).
// See Also: aWM_POINTER , WBMouseCancel()
void (*get_row_col)(WBChildFrame *, int *piR, int *piC);
// Obtain the current row/column cursor location for UI notification.
// 'piR' points to an integer to get the row, and
// 'piC' points to an integer to get the column.
// Both are 1-based values (<= 0 is 'error' or 'NA')
// returns non-zero value if there is a selection
void (*undo)(WBChildFrame *);
// perform an undo
void (*redo)(WBChildFrame *);
// perform a re-do
// returns non-zero value if 'can undo'
// returns non-zero value if 'can redo'
// returns non-zero value if contents are 'empty' (cannot select anything)

A window interface derived from 'WBChildFrame' needs a way for the 'abstract class' to invoke the UI functionality. To make this work, the 'superclass' (i.e. derived) window interface can populate a WBChildFrameUI structure with function pointers, as needed, to implement the necessary elements.

For those elements that are NOT implemented, you can use NULL for the function pointer. That way if the derived window interface does not need 'hover' support, you can leave the 'hover_notify' and 'hover_cancel' function pointers as NULL, but populate everything else.

For the 'iACS' parameters, use the 'iACS' information from the aWM_CHAR. This is the 'Alt/Ctrl/Shift' flag that indicates which of those buttons were being held down at the time of the character translation. For more information on THAT, see WM_CHAR.

The basic difference between 'do_char' and 'scancode' is that the 'character' events will be passed along to the 'do_char' callback, but 'scan code' events (NOT processed by one of the other callbacks) will be passed along via the 'scancode' callback. This will allow your custom UI handler to interpret additional 'special' keys as needed. The ones normally processed are: insert, delete, home, end, pgup, pgdown, and the 'F1' key.

NOTE: if a menu defines hotkey combinations, no 'WM_CHAR' event will be generated for any of those. Instead, the menu handler needs to interpret them correctly if the UI callback will need to be invoked. One example in the X11workbench.c handler (for the main edit window UI) is the handling of the 'Edit' sub-menu, which includes hotkey combinations such as 'CTRL+V' for 'paste'. When the 'paste' menu is invoked, the handler will need to grab the WBChildFrameUI structure for the currently active Child Window, and invoke its 'paste_from_cb' callback function directly. Similarly, if 'F1' is invoked, it will need to call the 'help' function directly, passing the correct 'iACS' parameter value.

Enumeration Type Documentation

enumeration for 'fFlags' member of WBChildFrame

Enumerator
WBChildFrame_NO_TAB 

does not use MDI tabs [intended for SDI interface]

WBChildFrame_PIXELS 

use PIXELS instead of characters and lines to define the viewport

WBChildFrame_VSPLIT 

RESERVED - 'splitter' window with vertical sizeable 'split'.

WBChildFrame_HSPLIT 

RESERVED - 'splitter' window with horizontal sizeable 'split'.

WBChildFrame_SPLIT_MASK 

RESERVED - bit mask for 'splitter' flags.

WBChildFrame_SPLIT_NOSIZE 

RESERVED - bit set if split cannot be sized with the mouse.

Definition at line 727 of file frame_window.h.

Function Documentation

int FWChildFrameEvent ( Window  wID,
XEvent *  pEvent 
)

Default event handler for Child Frame window.

Parameters
wIDA valid Window ID for a Child Frame window
pEventA pointer to the XEvent structure
Returns
An integer value, in which zero indicates "not handled", and non-zero indicates "handled"

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

Header File: child_frame.h

Definition at line 750 of file child_frame.c.

int FWChildFrameQueryClose ( WBChildFrame pChildFrame)

Returns if it's safe to close the child frame; prompts user as needed.

Parameters
pChildFrameThe pointer to the WBChildFrame structure for the desired Child Frame window
Returns
An integer value, 0 for 'ok to close', 1 for 'not ok to close', -1 on error

Use this function to safely determine whether it's ok to close a WBChildFrame window. The user may be prompted.

Internally, this will send a QUERY_CLOSE Client Message Event to the handler function. the default is to return a zero value, which is 'ok to close'. Your own function needs to handle this to prompt to save unsaved data and allow the user to cancel (thus returning a '1'). The message is invoked via an 'internal' Send Event which will directly call the handler functions.

Header File: child_frame.h

Definition at line 716 of file child_frame.c.

void FWChildFrameRecalcLayout ( WBChildFrame pChildFrame)

Child frame notification callback (called by frame window)

Parameters
pChildFrameThe pointer to the WBChildFrame structure for the desired Child Frame window

The frame window will call this function whenever the layout changes, including at the point the child frame is added to the frame window. Internally, it will call the user-defined event handler function with an event type of 'ClientMessage' and message type RESIZE_NOTIFY

The 'superclass' user-defined event handler MUST update scroll bar info when it receives this message, in order for scrolling to work correctly, and should NOT call FWChildFrameRecalcLayout() when processing the aRESIZE_NOTIFY message.

Header File: child_frame.h

Definition at line 609 of file child_frame.c.

void FWChildFrameStatusChanged ( WBChildFrame pChildFrame)

Notify Child Frame to update status text in Frame Window.

Parameters
pChildFrameThe pointer to the WBChildFrame structure for the desired Child Frame window

This function notifies the Child Frame that the status has changed, and it needs to update the status text in the associated Frame Window. The status text is NOT generated by the child frame object itself; rather, the derived 'superclass' window updates it internally. This function is simply a notification to update the frame window display. It may be called internally, or at any time whenever the status might have changed. This includes 'tab switch'.

Header File: child_frame.h

Definition at line 700 of file child_frame.c.

void FWDestroyChildFrame ( WBChildFrame pChildFrame)

Destroy an Child Frame.

Parameters
pChildFrameA pointer to the WBChildFrame structure for the Child Frame
Returns
void

Call this function to destroy the actual window and de-reference

Header File: child_frame.h

Definition at line 306 of file child_frame.c.

static __inline__ WBChildFrame* FWGetChildFrameStruct ( Window  wID)
static

Obtain the associated WBChildFrame structure pointer for a Window ID.

Parameters
wIDA valid Window ID
Returns
A pointer to the associated WBChildFrame structure (if it is a WBChildFrame), or NULL on error

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

Header File: child_frame.h

Definition at line 355 of file child_frame.h.

int FWInitChildFrame ( WBChildFrame pChildFrame,
WBFrameWindow pOwner,
XFontSet  rFontSet,
const char *  szFocusMenu,
const WBFWMenuHandler pHandlerArray,
WBWinEvent  pUserCallback,
int  fFlags 
)

Initialize a child frame (assumed to be a base 'class' for the window)

Parameters
pChildFramea pointer to the WBChildFrame associated with the window. Can not be NULL.
pOwnerA pointer to the owning WBFrameWindow. Can not be NULL.
rFontSetThe desired font set, or 'None' to use the default
szFocusMenuA const pointer to a text-based menu resource describing the menu that should appear when the Child Frame's tab has the focus. Can be NULL if none.
pHandlerArrayA const pointer to an array of WBFWMenuHandler structures for the 'focus' menu handler. Can be NULL if none.
pUserCallbackA pointer to the callback function that handles messages (Return 0 for default handling, != 0 if handled). Can be NULL.
fFlagsA bitwise 'or' of the desired flags associated with this Child Frame. See 'WBChildFrame_FLAGS'
Returns
an integer value, 0 on success, anything else being an error code

This function creates the actual window for a 'derived' Child Frame window, and correctly initializes that portion of the internal data structure corresponding to a Child Frame. The 'WBChildFrame' should normally be the first member of the data structure representing the 'derived' Child Frame window, so you can do a direct type cast of the pointer, similar to the way abstraction and polymorphism works in C++.
A child frame is not created directly. Instead, create the 'derived' version's structure, and initialize the structure for the derived behavior, with the WBChildFrame structure as the first element. Then initialize the WBChildFrame structure with this function, which will create the child frame window ID and register it with the specified WBFrameWindow.
Failure to call this function will prevent the 'Child Frame' functionality from working correctly, and will not register the relationship between the Window ID and the WBChildFrame structure.

NOTE: To create a stand-alone 'derived' Child Frame, first create a minimal frame window, with disabled 'tabs'. Then, create the Child Frame 'derived' window using WBInitChildFrame(). Only one will be allowed.
NOTE 2: If WBInitChildFrame() returns a non-zero value, do NOT call WBDestroyChildFrame() on that WBChildFrame .

See Also
Frame Windows

Header File: child_frame.h

Definition at line 109 of file child_frame.c.

void FWSetChildFrameDisplayName ( WBChildFrame pChildFrame,
const char *  szDisplayName 
)

Assign the display name.

Parameters
pChildFrameThe pointer to the WBChildFrame structure for the desired Child Frame window
szDisplayNameA pointer to a character array containing the new display name text, to appear in the tab and/or title bar

Assigns the display name for the Child Frame, to appear in the tab and (optionally) in the frame window's title bar whenever the Child Frame has the focus.

Header File: child_frame.h

Definition at line 536 of file child_frame.c.

void FWSetChildFrameExtent ( WBChildFrame pChildFrame,
int  iXExtent,
int  iYExtent 
)

Set the X,Y extent for the child frame (notifies everything)

Parameters
pChildFrameThe pointer to the WBChildFrame structure for the desired Child Frame window
iXExtentthe 'X' extent of the display surface
iYExtentthe 'Y' extent of the display surface

Use this function to assign the X and Y extents for the display surface on a Child Frame window. Calling this function will set up the scrolling behavior as well as notifying 'everything' of the changes, such as re-painting the window or re-sizing something.

A 'superclass' callback function handling aRESIZE_NOTIFY should not call this function. Instead, it should call FWSetChildFrameScrollInfo() instead, which will not cause recursion.

Header File: child_frame.h

Definition at line 570 of file child_frame.c.

void FWSetChildFrameImageAtom ( WBChildFrame pChildFrame,
Atom  aImage 
)

Assign the image atom for the child frame. the image appears in the tab associated with the child frame.

Parameters
pChildFrameThe pointer to the WBChildFrame structure for the desired Child Frame window
aImageAn atom that identifies the registered image. The default is no image. For more information, see PXM_RegisterPixmapResource().

Assigns the Atom for the image to be displayed in the tab. The default is no image. The image will appear on the far left edge of the tab, before the tab text. Typically it will be an icon-like image that represents the contents of the document being viewed/edited in that particular tab.
the image should be approximately 16 pixels high, and approximately 12 pixels wide, in order to to properly fit.

Header File: child_frame.h

Definition at line 558 of file child_frame.c.

void FWSetChildFrameMenu ( WBChildFrame pChildFrame,
const char *  szFocusMenu 
)

Function to assign the menu resource to a Child Frame.

Parameters
pChildFrameThe pointer to the WBChildFrame structure for the desired Child Frame window
szFocusMenuA const pointer to a text-based menu resource describing the menu that should appear when the Child Frame's tab has the focus

Assigns the (new) menu for the Child Frame. The text will be copied, and the copy will be used internally, and free'd as necessary. Only valid when the owner is a Frame Window.

Header File: child_frame.h

Definition at line 455 of file child_frame.c.

void FWSetChildFrameMenuHandlers ( WBChildFrame pChildFrame,
const WBFWMenuHandler pHandlerArray 
)

Function to assign menu handlers to a Child Frame.

Parameters
pChildFrameThe pointer to the WBChildFrame structure for the desired Child Frame window
pHandlerArrayA pointer to an array of WBFWMenuHandler structures -
See Also
FW_MENU_HANDLER_ENTRY

Assigns the (new) menu handlers for the Child Frame. The array will be copied, and the copy will be used internally, and free'd as necessary.

Header File: child_frame.h

Definition at line 480 of file child_frame.c.

void FWSetChildFrameScrollInfo ( WBChildFrame pChildFrame,
int  iRow,
int  iMaxRow,
int  iCol,
int  iMaxCol,
int  iRowHeight,
int  iColWidth 
)

Set the X,Y extent for the child frame (notifies everything)

Parameters
pChildFrameThe pointer to the WBChildFrame structure for the desired Child Frame window
iRowThe current row (0-based) for the cursor
iMaxRowThe total number of rows in the current object being displayed or edited
iColThe current column (0-based) for the cursor
iMaxColThe maximum number of columns in the current object being displayed or edited
iRowHeightThe height of a single row (in pixels). For text, this would be the font height plus row spacing.
iColWidthThe width of a single column (in pixels). For text, this would be the average character width.

Use this function to assign the current scroll information and update the 'extent' information (similar to 'FWSetChildFrameExtent()'). It is safe to call this from within the 'superclass' callback function that is handling an aRESIZE_NOTIFY Client Message event.

Header File: child_frame.h

Definition at line 588 of file child_frame.c.