| X-Designer User's Guide |    
|
| X-Designer User's Guide |
|
| A P P E N D I X 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 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 X-Designer, allowing you to add to it if you wish.
It is located in $XDROOT/src/motifxp/lib (where $XDROOT is the path to the root of the X-Designer 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 $XDROOT/src/motifxp/h directory.
The class CObject is the principal base class for the XP library. All other classes are derived from this one.
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 X-Designer to support the ApplicationShell widget.
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.
Returns the length of the widget's XmNtitle resource. Returns 0 if the widget has not yet been created.
Sets the XmNtitle and XmNiconName for the Shell widget to lpszString.
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:
Gets the window text for the widget. This is implemented by calling the virtual member function xd_get_window_text().
Gets the length of the window text for the widget. This is implemented by calling the virtual member function xd_get_window_text_length().
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.
Sets the window text for the widget. This is implemented by calling the virtual member function xd_set_window_text().
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().
The first version of xd_call_data() is used by the X-Designer generated code to store a callback's call_data in the class. It can be retrieved in the callback method using the second version.
Used by the sub-classes to implement GetWindowText().
Used by the sub-classes to implement GetWindowTextLength().
Used by the sub-classes to implement SetWindowText().
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.
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.
Returns the length of the widget's XmNtitle resource. Returns 0 if the widget has not yet been created.
Sets the XmNtitle and XmNiconName for the Shell widget to lpszString.
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. You can use either of these routines.
If the widget has been created sets lpMinPos and lpMaxPos to XmNminimum and XmNmaximum respectively.
If the widget has been created sets XmNvalue to nPos and returns the previous XmNvalue, otherwise returns 0. You can use either of these routines.
If the widget has been created sets XmNminimum and XmNmaximum to nMinPos and nMaxPos respectively.
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, LPCSTR lpszDefExt = NULL, LPCSTR lpszFileName = NULL, DWORD dwFlags = OFN_HIDEREADONLY |OFN_OVERWRITEPROMPT, LPCSTR lpszFilter = NULL, CWnd* pParentWnd = NULL); |
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.
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.
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.
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 X-Designer 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.
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.
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.
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.
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.
Used by the toolkit to map IDs to menu items.
Used by the toolkit to map IDs to menu items.
Used by the toolkit to map IDs to menu items.
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.
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.
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.
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.
Returns -1 if the widget has not yet been created, and 0 if it has. This corresponds to MFC behavior.
The class CStatic implements a Microsoft Windows static control which is a simple text field, implemented with a Label widget.
Sets the XmNlabelString resource for the widget to an XmString created with XmStringCreateLocalized() using lpszString.
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.
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.
Sets the XmNlabelString resource for the widget to an XmString created with XmStringCreateLocalized() using lpszString.
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.
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.
Overrides the methods in CObject so that the class can distinguish between List and ScrolledList.
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.
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.
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.
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.
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.
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.
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.
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.
Overrides the methods in CObject so that the class can distinguish between Text and ScrolledText.
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()).
Gets the start and end of the selected text. Returns start and end as 0 if there is no selected text.
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()).
Replaces the current selection with the text supplied in lpszNewText. If there is no selection the text is inserted at the insert cursor position.
Sets the XmNeditable resource of the widget to be !bReadOnly. Returns 0 if the widget has not yet been created, otherwise returns 1.
Sets the current selection to the text specified by nStartChar and nEndChar. Will also set XmNautoShowCursorPosition to !bNoScroll.
Sets the value for the widget to lpszString (XmTextSetString()).
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.
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.
The name of the application. This comes from the parameter passed to the CWinApp constructor.
The main window (ApplicationShell) of the application.
These two functions store and retrieve the applications Display connection.
These two functions store and retrieve the argv parameters passed into main().
These two functions store and retrieve the argc parameter passed into main().
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:
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 $XDROOT/src/motifxp/h (where $XDROOT is the path to the root of the X-Designer installation directory).
2. Locate the following lines:
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:
5. Recompile your generated code.
The application should now link successfully.
| X-Designer User's Guide | 817-5581-10 |
|
Copyright © 2003, Sun Microsystems, Inc. All rights reserved.