APPENDIX B |
Motif XP Reference |
The Motif XP library allows you to share code between Motif and Microsoft Windows by providing a mapping of most of the MFC classes and methods to Motif widgets and X or UNIX calls. This chapter documents the library.
To make full use of the following information, start by checking which MFC class you are dealing with. "Mapping Motif Widgets to Microsoft Windows" on page 786 will give you this information. You can then look up the class in the following pages and find which methods are available.
Note - All variables and methods beginning xd_ are specific to the Motif XP - you can use them on Motif but not on Microsoft Windows.
For information on the MFC and the methods, you should consult your MFC documentation supplied with the environment you are using on Microsoft Windows.
The source code for the Motif XP is provided with Sun WorkShop Visual, allowing you to add to it if you wish.It is located in $VISUROOT/src/motifxp/lib (where $VISUROOT is the path to the root of the Sun WorkShop Visual installation directory). Each class has a separate source file and is commented to help you find your way around. The public headers are in xdclass.h which can be found in the $VISUROOT/src/motifxp/h directory.
The class CObject is the principal base class for the XP library. All other classes are derived from this one.virtual Widget xd_rootwidget(); and virtual void xd_rootwidget( Widget xd_rootwidget );
The first version of xd_rootwidget() returns the widget pointer of the widget at the root of the hierarchy which is represented by the CObject object. The second version sets the root widget.
The class CFrameWnd provides the functionality of a Microsoft Windows single document interface overlapped or pop-up frame window. It is used by Sun WorkShop Visual to support the ApplicationShell widget.protected virtual int xd_get_window_text(LPSTR lpszStringBuf, int nMaxCount) const;
Gets the value of XmNtitle for the Shell widget. Returns 0 if the widget has not yet been created, otherwise returns the length of the text.
protected virtual int xd_get_window_text_length() const;
Returns the length of the widget's XmNtitle resource. Returns 0 if the widget has not yet been created.
protected virtual void xd_set_window_text(LPCSTR lpszString);
Sets the XmNtitle and XmNiconName for the Shell widget to lpszString.
protected virtual BOOL xd_show_window(int nCmdShow);
Used to implement ShowWindow for ApplicationShell. Supports SW_SHOWMINIMIZED, SW_HIDE and SW_RESTORE only.
The class CCmdTarget is the base class for the XP library message-map architecture. A message map routes commands or messages to the member functions you write to handle them. This Motif version includes no functionality; the class is included only for compatibility with the Microsoft Windows code.
The class CWnd provides the base functionality of all window classes in the XP library. The following MFC methods have been implemented:int GetWindowText(LPSTR lpszStringBuf, int nMaxCount) const;
Gets the window text for the widget. This is implemented by calling the virtual member function xd_get_window_text().
int GetWindowTextLength() const;
Gets the length of the window text for the widget. This is implemented by calling the virtual member function xd_get_window_text_length().
BOOL EnableWindow(BOOL bEnable=TRUE);
Enables or disables a window. Returns 0 if the widget has not yet been created, 0 if the widget was previously enabled or non-zero if the widget was previously disabled.
void SetWindowText(LPCSTR lpszString);
Sets the window text for the widget. This is implemented by calling the virtual member function xd_set_window_text().
BOOL ShowWindow(int nCmdShow);
Show, iconize (ApplicationShell or TopLevelShell only) or hide a window. Returns 0 if the widget has not yet been created; 0 if the window was previously hidden or non-zero if the window was previously visible. It is implemented by calling the virtual member function xd_show_window().
void xd_call_data ( XmAnyCallbackStruct *call_data); and XmAnyCallbackStruct *xd_call_data () { return _xd_call_data; }
The first version of xd_call_data() is used by the Sun WorkShop Visual generated code to store a callback's call_data in the class. It can be retrieved in the callback method using the second version.
protected virtual int xd_get_window_text(LPSTR lpszStringBuf, int nMaxCount) const;
Used by the sub-classes to implement GetWindowText().
protected virtual int xd_get_window_text_length() const;
Used by the sub-classes to implement GetWindowTextLength().
protected virtual void xd_set_window_text(LPCSTR lpszString);
Used by the sub-classes to implement SetWindowText().
protected virtual BOOL xd_show_window(int nCmdShow);
Implements default show and hide behavior for ShowWindow. For gadgets it manages and unmanages the gadget, for widgets it sets mappedWhenManaged appropriately.
The class CDialog is the base class used for displaying dialog boxes on the screen. To make a useful class, you would normally derive another class from CDialog.protected virtual int xd_get_window_text(LPSTR lpszStringBuf, int nMaxCount) const;
Gets the value of XmNtitle for the Shell widget. Returns 0 if the widget has not yet been created, otherwise returns the length of the text and the text is placed into lpszStringBuf.
protected virtual int xd_get_window_text_length() const;
Returns the length of the widget's XmNtitle resource. Returns 0 if the widget has not yet been created.
protected virtual void xd_set_window_text(LPCSTR lpszString);
Sets the XmNtitle and XmNiconName for the Shell widget to lpszString.
protected virtual BOOL xd_show_window(int nCmdShow);
Implements ShowWindow for TopLevelShell or DialogShell. Supports SW_SHOWMINIMIZED (TopLevelShell only), SW_HIDE and SW_RESTORE.
The class CScrollBar provides the functionality of a Microsoft Windows scroll-bar control.Returns 0 if the widget has not yet been created, otherwise returns XmNvalue.
void GetScrollRange(LPINT lpMinPos, LPINT lpMaxPos) const;
If the widget has been created sets lpMinPos and lpMaxPos to XmNminimum and XmNmaximum respectively.
int SetScrollPos(int nPos, BOOL bRedraw = TRUE);
If the widget has been created sets XmNvalue to nPos and returns the previous XmNvalue, otherwise returns 0.
void SetScrollRange(int nMinPos, int nMaxPos, BOOL bRedraw = TRUE);
If the widget has been created sets XmNminimum and XmNmaximum to nMinPos and nMaxPos respectively.
void ShowScrollBar(BOOL bShow = TRUE);
If the widget has been created manages or unmanages it as determined by bShow.
The CFileDialog class encapsulates the Microsoft Windows common file dialog box, providing an easy way to implement File Open and File Save As dialog boxes (as well as other file selection dialog boxes) in a manner consistent with Microsoft Windows standards.CFileDialog (BOOL bOpenFileDialog,The constructor simply builds a CFileDialogObject. The lpszFileName and lpszFilter parameters are used to set the XmNdirSpec and XmNpattern resources of the file selection box in the DoModal() method. The pParentWnd resource should point to a CFrameWnd object.
LPCSTR lpszDefExt = NULL,
LPCSTR lpszFileName = NULL,
DWORD dwFlags =
OFN_HIDEREADONLY |OFN_OVERWRITEPROMPT,
LPCSTR lpszFilter = NULL,
CWnd* pParentWnd = NULL);Destroys the CFileDialog object, freeing private class variables.
Sets the XmNdirSpec and XmNpattern resources as specified in the constructor then executes a private event loop until the OK, Cancel, or Popdown callback is processed.
Returns the value of the file selection box's XmNdirSpec resource.
protected virtual void OnCancel();
Called when the user presses the Cancel button or pops down the dialog from the window menu. Sub-classes should call this method when overriding OnCancel() if they want the file selection to complete.
protected virtual void OnOK();
Called when the user presses the OK button. Sub-classes should call this method when overriding OnOk() if they want the file selection to complete.
Returns True by default. This is overridden in Sun WorkShop Visual generated code to call the create method which will create the widgets.
Used to implement PanedWindows.
The class CMenu is a class for handling the Microsoft Windows menu control.UINT CheckMenuItem(UINT nIDCheckItem, UINT nCheck);
Sets the check state for a menu item which corresponds to a toggle button. The nCheck parameter specifies both the required state of the item (MF_CHECKED or MF_UNCHECKED) and the interpretation of nIDCheckItem (MF_BYCOMMAND and MF_BYPOSITION). These two values should be specified using bitwise OR (e.g. menu->CheckMenuItem ( ID_toggle_b, MF_BYCOMMAND | MF_CHECKED )). The function returns -1 if the menu item is not found or is not a toggle button (note that the MFC will allow any menu item to be checked - even a separator). The previous state (MF_CHECK or MF_UNCHECKED) is returned otherwise. If nCheck includes MF_BYCOMMAND any submenus are also searched.
UINT EnableMenuItem(UINT nIDEnableItem, UINT nEnable);
Enables or Disables a menu item. The nEnable parameter specifies both the required state of the item (MF_ENABLED or MF_GRAYED) and the interpretation of nIDEnableItem (MF_BYCOMMAND and MF_BYPOSITION). These two values should be specified using bitwise OR (e.g. menu->EnableMenuItem ( ID_toggle_b, MF_BYCOMMAND | MF_GRAYED )). The function returns -1 if the menu item is not found or is a menubar, menu, separator or a cascade button and MF_BYCOMMAND is specified. The previous state ( MF_ENABLED or MF_GRAYED) is returned otherwise. If nEnable includes MF_BYCOMMAND any submenus are also searched. Note that the state MF_DISABLED (insensitive but not grayed out) is not supported.
UINT GetMenuState(UINT nID, UINT nFlags)const;
Gets the state of a menu item. The nFlags parameter specifies the interpretation of nID (MF_BYCOMMAND or MF_BYPOSITION). The function returns -1 if the menu item is not found or is a separator and MF_BYCOMMAND is specified. A bitwise OR of the states (MF_CHECKED, MF_UNCHECKED, MF_SEPARATOR, MF_ENABLED or MF_GRAYED) is returned otherwise. If nFlags is MF_BYCOMMAND any submenus are also searched. Note that in MFC, GetMenuState for a popup menu also returns the number of items in the high order byte. This is not supported by the Motif XP.
BOOL TrackPopupMenu ( UINT nFlags, int x, int y, CWnd *pWnd,
LPCRECT lpRect = 0 );This function simulates the behavior of the MFC TrackPopupMenu function. The function retrieves the call_data from the window specified by pWnd (this will have been saved by the callback function). If the event in the call_data is a ButtonPress event the popup menu is positioned using the call_data's event (not the function parameters), the menu is managed and TRUE is returned. FALSE is returned otherwise.
void xd_register_menu(CMenu *menu);
Used by the toolkit to map IDs to menu items.
void xd_register_menu_item(UINT nIDItem, Widget item);
Used by the toolkit to map IDs to menu items.
protected Widget xd_get_menu_item_by_position(UINT nPos);
Used by the toolkit to map IDs to menu items.
protected Widget xd_get_menu_item_by_id(UINT nIDItem);
Used by the toolkit to map IDs to menu items.
The class CComboBox is used to wrap an OptionMenu to provide an interface equivalent to the ComboBox.Returns the (zero based) index of the currently selected item. Returns 0 if the widget has not yet been created.
int GetLBText(int nIndex, LPSTR lpszText) const;
Gets a copy of the text of the item into lpszText identified by nIndex and returns its length. Returns 0 if the widget has not yet been created and LB_ERR if the index is out of range.
int GetLBTextLen(int nIndex) const;
Returns the length of the text of the item identified by nIndex. Returns 0 if the widget has not yet been created and LB_ERR if the index is out of range.
Sets the current selection to be the item identified by nSelect. Returns 0 if the widget has not yet been created and LB_ERR if the index is out of range. Otherwise returns the index of the selected item. Note unlike MFC passing nSelect as -1 to clear the selection is not supported.
protected virtual int xd_get_window_text(LPSTR lpszStringBuf, int nMaxCount) const;
Returns the text of the selected item in lpszStringBuf. Returns 0 if the widget has not been created, LB_ERR if there is no selected item, the length of the text otherwise.
protected virtual int xd_get_window_text_length() const;
Returns -1 if the widget has not yet been created, and 0 if it has. This corresponds to MFC behavior.
protected virtual void xd_set_window_text(LPCSTR);
The class CStatic implements a Microsoft Windows static control which is a simple text field, implemented with a Label widget.protected virtual void xd_set_window_text(LPCSTR lpszString);
Sets the XmNlabelString resource for the widget to an XmString created with XmStringCreateLocalized() using lpszString.
protected virtual int xd_get_window_text(LPSTR lpszStringBuf, int nMaxCount) const;
Gets the value of XmNlabelString for the widget into lpszStringBuf. If the widget has not yet been created 0 is returned, otherwise the length of the string is returned.
protected virtual int xd_get_window_text_length() const;
Returns the length of the XmNlabelString resource for the widget. If the widget has not yet been created 0 is returned.
The CButton class provides the functionality of Microsoft Windows button controls and is implemented with either a PushButton or a ToggleButton.Gets the check state of a button. Returns 0 if the widget has not yet been created, is not a toggle button or is a toggle button and is not set. Returns 1 if the toggle button is set. Note that the MFC can return a value 2 (indeterminate state) which is not supported by the Motif XP.
Sets the state of a toggle button according to nCheck. This is a noop for push buttons.
protected virtual void xd_set_window_text(LPCSTR lpszString);
Sets the XmNlabelString resource for the widget to an XmString created with XmStringCreateLocalized() using lpszString.
protected virtual int xd_get_window_text(LPSTR lpszStringBuf, int nMaxCount) const;
Gets the value of XmNlabelString for the widget into lpszStringBuf. If the widget has not yet been created 0 is returned, otherwise the length of the string is returned.
protected virtual int xd_get_window_text_length() const;
Returns the length of the XmNlabelString resource for the widget. If the widget has not yet been created 0 is returned.
The class CBitmapButton implements a button with a bitmap instead of text.
The class CListBox provides the functionality of a list box which can display a list of items that the user can view and select.virtual Widget xd_rootwidget(); and virtual void xd_rootwidget( Widget xd_rootwidget );
Overrides the methods in CObject so that the class can distinguish between List and ScrolledList.
virtual Widget xd_listwidget();
Returns the list widget for the object. For an ordinary List this is the same as the root widget, however, it is different for a ScrolledList.
int DeleteString(UINT nIndex);
Deletes the list item identified by nIndex (zero based). Returns 0 if the widget has not yet been created, LB_ERR if the index is out of range or the number of items remaining in the list.
Returns 0 if the widget has not yet been created, otherwise returns the number of items in the list (XmNitemCount).
Gets the index of the currently selected item in a single select list (XmNselectionPolicy is XmSINGLE_SELECT or XmBROWSE_SELECT). Returns 0 if the widget has not yet been created, LB_ERR if the list is a multiple selection list or it has not selected item. Otherwise the index of the selected item is returned. Note that the MFC returns an arbitrary positive value if the list is a multiple selection list, Motif XP always returns LB_ERR.
Returns the selection state of the item indicated by nIndex. Returns 0 if the widget has not yet been created or if the item is not selected. Returns LB_ERR if the index is out of range, or a positive value if the item is selected.
Returns the number of selected items in a multiple selection list. Returns 0 if the widget has not yet been created, LB_ERR if the list is a single selection list, or the number of selected items otherwise.
int GetSelItems(int nMaxItems, LPINT rgIndex) const;
Gets the indices of the selected items in a multiple selection list and copies them into the array rgIndex. Returns 0 if the widget has not yet been created, LB_ERR if the list is a single selection list, or the number of indices copied otherwise.
int GetText(int nIndex, LPSTR lpszBuffer) const;
Gets the text of an item identified by nIndex into lpszBuffer. Returns 0 if the widget has not yet been created, LB_ERR if the index is out of range, the length of the text otherwise.
int GetTextLen(int nIndex) const;
Gets the length of the text of an item identified by nIndex. Returns 0 if the widget has not yet been created, LB_ERR if the index is out of range, the length of the text otherwise.
Returns the index of the item that is visible at the top of the list. Returns 0 if the widget has not yet been created.
int InsertString(int nIndex, LPCSTR lpszItem);
Inserts an item into the list at the position given by nIndex, If nIndex is -1 the item is appended at the end of the list. Returns 0 if the widget has not yet been created, LB_ERR if the index is out of range, the position at which the item was inserted otherwise.
Removes all the items from a list.
int SelItemRange(BOOL bSelect, int nFirstItem, int nLastItem);
Selects or deselects, according to bSelect, a range of items in a multiple selection list. Returns 0 if the widget has not yet been created, LB_ERR if the list is a single selection list, a value other than LB_ERR otherwise.
Select an item, identified by nSelect, in a single selection list and scroll it into view. If nSelect is -1, the selection is cleared. Returns 0 if the widget has not yet been created, LB_ERR if the list is a multiple selection list or the index is out of range, a value other than LB_ERR otherwise.
int SetSel(int nIndex, BOOL bSelect = TRUE);
Selects or deselects, according to bSelect, an item in a multiple selection list. If nIndex is -1 all items are selected or deselected. Returns 0 if the widget has not yet been created, LB_ERR if the list is a single selection list or the index is out of range, a value other than LB_ERR otherwise.
Scroll the list to make the item identified by nIndex visible. Returns 0 if the widget has not yet been created, LB_ERR if the index is out of range, a value other than LB_ERR otherwise.
The class CEdit provides the functionality of a Microsoft Windows edit control which is a rectangular window in which the user can enter text. Implemented with either a Text or TextField widget.virtual Widget xd_rootwidget(); and virtual void xd_rootwidget( Widget xd_rootwidget );
Overrides the methods in CObject so that the class can distinguish between Text and ScrolledText.
virtual Widget xd_textwidget();
Returns the text widget for the object. For ordinary Text this is the same as the root widget, however, it is different for ScrolledText.
Deletes the currently selected text (XmTextRemove()).
Copies the currently selected text to the clipboard (XmTextCopy()).
Deletes the currently selected text and copies it to the clipboard. (XmTextCut()).
void GetSel(int &nStartChar, int &nEndChar) const;
Gets the start and end of the selected text. Returns start and end as 0 if there is no selected text.
void LimitText(int nChars = 0);
Limit the number of characters that can be typed. If nChars is 0 the limit is set to maximum.
Insert data from the clipboard into the text widget (XmTextPaste()).
void ReplaceSel(LPCSTR lpszNewText);
Replaces the current selection with the text supplied in lpszNewText. If there is no selection the text is inserted at the insert cursor position.
BOOL SetReadOnly(BOOL bReadOnly = TRUE);
Sets the XmNeditable resource of the widget to be !bReadOnly. Returns 0 if the widget has not yet been created, otherwise returns 1.
void SetSel(int nStartChar, int nEndChar, BOOL bNoScroll = FALSE);
Sets the current selection to the text specified by nStartChar and nEndChar. Will also set XmNautoShowCursorPosition to !bNoScroll.
protected virtual void xd_set_window_text(LPCSTR lpszString);
Sets the value for the widget to lpszString (XmTextSetString()).
protected virtual int xd_get_window_text(LPSTR lpszStringBuf, int nMaxCount) const;
Gets the text from the widget (XmTextGetString()) into lpszStringBuf. If the widget has not yet been created 0 is returned, otherwise the length of the string is returned.
protected virtual int xd_get_window_text_length() const;
Returns the length of the widget's text. If the widget has not yet been created 0 is returned.
The class CWinApp is the base class from which you derive a Microsoft Windows application object for initializing your application and for running the application.CWinApp(const char* pszAppName = NULL);
The name of the application. This comes from the parameter passed to the CWinApp constructor.
The main window (ApplicationShell) of the application.
Display *xd_display(); and void xd_display(Display *display);
These two functions store and retrieve the applications Display connection.
char **xd_argv() const; and void xd_argv(char **argv);
These two functions store and retrieve the argv parameters passed into main().
int xd_argc() const; and void xd_argc(int argc);
These two functions store and retrieve the argc parameter passed into main().
char *xd_app_class() const; and void xd_app_class(char *app_class);
These two functions store and retrieve the application class name used in XtOpenDisplay().
Returns the one, and only, instance of a CWinApp object.
Some C++ compilers will fail to link, producing the following sort of errors:Undefined symbolCWnd::xd_get_window_text_length(void) constCFrameWnd::xd_get_window_text_length(void) constCButton::xd_get_window_text_length(void) constCButton::__vtblCMenu::xd_register_menu_item(unsigned int, _WidgetRec*)CDialog::xd_show_window(int)CDialog::xd_get_window_text_length(void) constCDialog::xd_set_window_text(const char*)CEdit::__vtbl
The compiler requires there to be an implementation of the copy constructor.
If this occurs, do the following:
| 1. | Find the header file xdclass.h in $VISUROOT/src/motifxp/h (where $VISUROOT is the path to the root of the Sun WorkShop Visual installation directory). |
| 2. | Locate the following lines: |
private:
// Certain C++ compilers (e.g. gcc 2.5) require there to be an
// implementation of the copy constructor. If your application
// fails to link try using the second version of the constructor
CObject(const CObject& objectSrc);
// no default copy
//CObject(const CObject& objectSrc) { abort();}
// no default copy
| 3. | Follow the instructions so that the first line beginning CObject is commented out and the second has the comment markers removed: |
// CObject(const CObject& objectSrc);
// no default copy
CObject(const CObject& objectSrc) { abort();}
// no default copy
| 4. | Add the following include line somewhere above the line containing the call to abort: |
#include <stdlib.h>
| 5. | Recompile your generated code. |
The application should now link successfully.