X11 Work Bench Toolkit  1.0
Edit Window APIs and Structures

Data Structures

struct  __WBEditWindow__
 Structure that defines an Edit Window. More...
 

Typedefs

typedef struct __WBEditWindow__ WBEditWindow
 Structure that defines an Edit Window. More...
 

Functions

WBEditWindowWBCreateEditWindow (WBFrameWindow *pOwner, XFontStruct *pFont, const char *szFocusMenu, const WBFWMenuHandler *pHandlerArray, int fFlags)
 Create an Edit Window. More...
 
void WBDestroyEditWindow (WBEditWindow *pEditWindow)
 Destroy an Edit Window. More...
 
WBEditWindowWBEditWindowFromWindowID (Window wID)
 Obtain the associated WBEditWindow structure pointer for a Window ID. More...
 
int WBEditWindowLoadFile (WBEditWindow *pEditWindow, const char *pszFileName)
 Open an existing file and read its contents into the Edit Window, storing the file name for later reference. More...
 
int WBEditWindowSaveFile (WBEditWindow *pEditWindow, const char *pszFileName)
 Save the contents from the Edit Window to a file, overwriting the file if it already exists. More...
 
void WBEditWindowClear (WBEditWindow *pEditWindow)
 Clear the contents in the Edit Window, and NULL the stored file name. More...
 
static __inline int WBIsValidEditWindow (WBEditWindow *pEditWindow)
 Check for valid WBEditWindow pointer. More...
 
void WBEditWindowRegisterCallback (WBEditWindow *pEditWindow, WBWinEvent pUserCallback)
 Clear the contents in the Edit Window, and NULL the stored file name. More...
 

Variables

Atom aEW_HOVER_NOTIFY
 Hover notification to user-callback, sent via ClientMessage event. More...
 
Atom aEW_EDIT_CHANGE
 'Edit Change' notification to user-callback, sent via ClientMessage event More...
 

Detailed Description

Edit windows are 'Child Frame' windows, owned by a frame window, in which text is edited and menu callbacks are processed.
The edited text is typically associated with a file name. An Edit Window uses the TEXT_OBJECT object (structure) to manage its state.

See Also
Text Editing Utilities and Objects

Typedef Documentation

Structure that defines an Edit Window.

The WBEditWindow structure defines an 'Edit Window' that is a 'superclass' of a Child Frame window. The first element MUST be the 'WBChildFrame'. Elements that follow it are specific to the Edit Window.

This uses a TEXT_OBJECT structure to store the actual text data, and to manage the UI functionality.

typedef struct __WBEditWindow__
{
WBChildFrame childframe; // elements common to a 'child frame' (derived object)
unsigned int ulTag; // 'Tag' identifying this structure as a WBEditWindow
char *szFileName; // malloc'd name of file associated with this edit window (NULL if none)
WBWinEvent pUserCallback; // user callback function to receive notifications and unhandled messages
TEXT_OBJECT xTextObject; // the 'TEXT_OBJECT' member, that does MOST of the work

Additional 'Child Frame' API functions can be called directly by using a type cast from 'WBEditWindow *' to 'WBChildFrame *', or by using the 'WBChildWindowFromWindowID()' function.

See Also
TEXT_OBJECT

Function Documentation

WBEditWindow* WBCreateEditWindow ( WBFrameWindow pOwner,
XFontStruct *  pFont,
const char *  szFocusMenu,
const WBFWMenuHandler pHandlerArray,
int  fFlags 
)

Create an Edit Window.

Parameters
pOwnerA pointer to the owning WBFrameWindow. Can not be NULL.
pFontThe desired font, or NULL 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.
fFlagsA bitwise 'or' of the desired flags associated with this Edit Window. See 'WBChildFrame_FLAGS'
Returns
a pointer to a WBEditWindow object describing the new edit window, or NULL on error

This function allows you to create an Edit Window that is a regular child of a frame window or dialog box, as a 'single document' handler. To create a window that uses the maximum available space within the client area of the parent, specify '-1' for iTop, iLeft, iWidth, and iHeight.

Header File: edit_window.h

Definition at line 249 of file edit_window.c.

void WBDestroyEditWindow ( WBEditWindow pEditWindow)

Destroy an Edit Window.

Parameters
pEditWindowA pointer to the WBEditWindow structure for the edit window
Returns
void

Call this function on any pointer returned by WBCreateEditWindow to destroy it and free its resources.

Header File: edit_window.h

Definition at line 377 of file edit_window.c.

void WBEditWindowClear ( WBEditWindow pEditWindow)

Clear the contents in the Edit Window, and NULL the stored file name.

Parameters
pEditWindowA pointer to the WBEditWindow structure

Use this function to clear an Edit Window, setting the file name to NULL

Header File: edit_window.h

Definition at line 473 of file edit_window.c.

WBEditWindow* WBEditWindowFromWindowID ( Window  wID)

Obtain the associated WBEditWindow structure pointer for a Window ID.

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

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

Header File: edit_window.h

Definition at line 419 of file edit_window.c.

int WBEditWindowLoadFile ( WBEditWindow pEditWindow,
const char *  pszFileName 
)

Open an existing file and read its contents into the Edit Window, storing the file name for later reference.

Parameters
pEditWindowA pointer to the WBEditWindow structure
pszFileNameA (const) pointer to a character string containing the file name. PATH rules will be used to locate the actual file.
Returns
A value of zero if successful, non-zero on error.

Use this function to read a file into the Edit Window, replacing any existing contents.

Header File: edit_window.h

Definition at line 433 of file edit_window.c.

void WBEditWindowRegisterCallback ( WBEditWindow pEditWindow,
WBWinEvent  pUserCallback 
)

Clear the contents in the Edit Window, and NULL the stored file name.

Parameters
pEditWindowA pointer to the WBEditWindow structure
pUserCallbackA pointer to the callback function that handles messages (Return 0 for default handling, != 0 if handled). Can be NULL.

Use this function to specify a user callback for an Edit Window. By using this function to specify the callback, you ensure that proper 'Edit Window' event handling will still occur.

As with other callback functions that use WBWinEvent as their data type, you nee to return a value of zero to indicate 'perform default handling', non-zero if you handle the event and do NOT want 'default' handling.

Edit Windows can generate a number of custom Client Message events that are specific to Edit Windows.

Header File: edit_window.h

Definition at line 486 of file edit_window.c.

int WBEditWindowSaveFile ( WBEditWindow pEditWindow,
const char *  pszFileName 
)

Save the contents from the Edit Window to a file, overwriting the file if it already exists.

Parameters
pEditWindowA pointer to the WBEditWindow structure
pszFileNameA (const) pointer to a character string containing the file name. PATH rules will be used to locate the actual file. A value of NULL uses the stored file name.
Returns
A value of zero if successful, non-zero on error.

Use this function to write the contents of an Edit Window to a file, overwriting any existing file of the same name.

Header File: edit_window.h

Definition at line 449 of file edit_window.c.

static __inline int WBIsValidEditWindow ( WBEditWindow pEditWindow)
static

Check for valid WBEditWindow pointer.

Parameters
pEditWindowA pointer to a WBEditWindow structure
Returns
non-zero if valid, zero if NOT valid

Header File: edit_window.h

Definition at line 273 of file edit_window.h.

Variable Documentation

Atom aEW_EDIT_CHANGE

'Edit Change' notification to user-callback, sent via ClientMessage event

EW_EDIT_CHANGE message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aEW_EDIT_CHANGE
format == 32 (always)
data.l[0] A value of 1 to indicate text added or deleted, 2 for a 're-do', or 0 for an un-do operation
" data.l[1] The current row (0-based) (hover notify only)
data.l[2] The current column (0-based) (hover notify only)

The Edit Window sends this event directly to the callback specified by WBEditWindowRegisterCallback() whenever the Edit Window text has been modified due to UI interaction. If no user callback is specified (i.e. it is NULL) no such event will be generated the window itself.

Definition at line 191 of file edit_window.c.

Atom aEW_HOVER_NOTIFY

Hover notification to user-callback, sent via ClientMessage event.

EW_HOVER_NOTIFY message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aEW_HOVER_NOTIFY
format == 32 (always)
data.l[0] A value of 1 to indicate 'hover notify', zero to indicate 'hover cancel'
data.l[1] The current row (0-based) (hover notify only)
data.l[2] The current column (0-based) (hover notify only)

The Edit Window sends this event directly to the callback specified by WBEditWindowRegisterCallback() whenever the Edit Window receives a hover notification. If no user callback is specified (i.e. it is NULL) no such event will be generated the window itself.

Definition at line 173 of file edit_window.c.