NAME¶
XbaeInput - The Input widget class.
SYNOPSIS¶
#include <Xbae/Input.h>
DESCRIPTION¶
XbaeInput is a text input field that provides generic customised data
entry and formatting for strings. It does this by using a clever
XmNmodifyVerifyCallback that is installed when the
XmNpattern
resource is set. The
XmNpattern value may include optional characters
and literals which will be discussed later in this document.
The
XbaeInput widget is ideal for restricting data input to a digit,
alphanumeric character or an alphabetic character. If
XmNconvertCase is
set, the widget automatically changes an inserted character to uppercase or
lowercase. Literal characters can also be included in the
XmNpattern
that can be automatically inserted as the user types by setting the
XmNautofill resource to True. Optional literals cannot be auto
inserted, however.
Unlike the
XmText field from which this widget is subclassed, the
toggle-overwrite action is bound to the
osfInsert key. The
XmNoverwriteMode is also provided to allow the resource to be changed
programatically.
When the
XbaeInput widget loses focus or is activated in the same way as
the
XmText field would be, callbacks on the XmNvalidateCallback list
are invoked, allowing the programmer to validate the data as well as
reformatting the existing string.
Classes¶
XbaeInput inherits behavior and resources from the
Core,
XmPrimitive, and
XmText widget classes.
The class pointer is
xbaeInputWidgetClass.
The class name is
XbaeInput.
New Resources¶
The following table lists the new resources defined by
XbaeInput. The
codes in the Access column indicate whether the given resource can be set at
creation time (C), or set by using XtSetValues (S), or retrieved by using
XtGetValues (G).
XbaeInput Resource Set |
|
|
|
|
|
Name |
Class |
Type |
Default |
Access |
|
XmNalignment |
XmCAlignment |
unsigned char |
XmALIGNMENT_BEGINNING |
CSG |
|
XmNautoFill |
XmCBoolean |
Boolean |
False |
CSG |
|
XmNconvertCase |
XmCBoolean |
Boolean |
True |
CSG |
|
XmNoverwriteMode |
XmCBoolean |
Boolean |
False |
CSG |
|
XmNpattern |
XmCString |
String |
NULL |
CSG |
|
XmNvalidateCallback |
XmCCallback |
Callback |
NULL |
CSG |
This resource has not been implemented.
- XmNalignment
- This resource has not been implemented!
Specifies the alignment of the text when being edited and displayed.
Possible values are XmALIGNMENT_BEGINNINGand
XmALIGNMENT_END. If XmNalignment is set to
XmALIGNMENT_END, the text will be right justified. If left as the
default of XmALIGNMENT_BEGINNING, the text will be left
justified.
- XmNautoFill
- The XmNautoFill resource, when set to True, attempts
to automatically insert a literal if a non literal is hit in an allowed
literal position. For example, if the XmNpattern resource was set
up to accept a date in dd/mm/yyyy format and the user typed
"18041999" The resulting string would appear as
"18/04/1999". The default value is False, where the user would
have to type the literal.
- XmNconvertCase
- Tells the XbaeInput widget what should be done to
alphabetic characters if the requires a lowercase or uppercase letter. If
the XmNconvertCase is set to True (default), then the character is
automatically converted to the correct case. If set to False, then the
user must type the character in the correct case in order for it to be
accepted. See the EXAMPLE PATTERNS section towards the end of this
document for some examples.
- overwriteMode
- Whether the widget accepts characters in insert mode or
overwrite mode is controlled by the resource. Setting this resource calls
the XmText toggle-overwrite() action routine, so the Motif
toolkit being used must also support this routine.
- XmNpattern
- The XmNpattern resource specifies what can be typed
into the XbaeInput widget. If set to the default value of
NULL any character may be entered. The XmNpattern
can be set to a string containing the following characters.
a |
alphabetic characters only |
b |
both - either digit or character |
c |
any character at all |
d |
digits only |
U |
upperchase character only |
L |
lowercase character only |
[ |
start of optional sequence |
] |
end of optional sequence |
\\ |
escapes the next character |
| |
next char is an alternative to previous. May be chained. |
Inherited Resources¶
The following table lists the resources which
XbaeInput inherits from
it's superclasses
XmText,
XmPrimitive and Core. For a
complete description of each resource, refer to the man page for that
superclass. The codes in the "Access" column indicate whether the
given resource can be set at creation time (C), or set by using XtSetValues
(S), or retrieved by using XtGetValues (G).
XmText Resource Set |
|
|
|
|
|
Name |
Class |
Type |
Default |
Access |
|
XmNautoShowCursorPosition |
XmCAutoShowCursorPosition |
Boolean |
True |
CSG |
|
XmNcursorPosition |
XmCCursorPosition |
XmTextPosition |
0 |
CSG |
|
XmNeditable |
XmCEditable |
Boolean |
True |
CSG |
|
XmNeditMode |
XmCEditMode |
int |
XmSINGLE_LINE_EDIT |
CSG |
|
XmNfocusCallback |
XmCCallback |
XtCallbackList |
NULL |
CSG |
|
XmNgainPrimaryCallback |
XmCCallback |
XtCallbackList |
NULL |
CSG |
|
XmNlosePrimaryCallback |
XmCCallback |
XtCallbackList |
NULL |
CSG |
|
XmNlosingFocusCallback |
XmCCallback |
XtCallbackList |
NULL |
CSG |
|
XmNmarginHeight |
XmCMarginHeight |
Dimension |
5 |
CSG |
|
XmNmarginWidth |
XmCMarginWidth |
Dimension |
5 |
CSG |
|
XmNmaxLength |
XmCMaxLength |
int |
largest integer |
CSG |
|
XmNmodifyVerifyCallback |
XmCCallback |
XtCallbackList |
NULL |
CSG |
|
XmNmodifyVerifyCallbackWcs |
XmCCallback |
XtCallbackList |
NULL |
CSG |
|
XmNmotionVerifyCallback |
XmCCallback |
XtCallbackList |
NULL |
CSG |
|
XmNsource |
XmCSource |
XmTextSource |
Default source |
CSG |
|
XmNtopCharacter |
XmCTextPosition |
XmTextPosition |
0 |
CSG |
|
XmNvalue |
XmCValue |
String |
"" |
CSG |
|
XmNvalueChangedCallback |
XmCCallback |
XtCallbackList |
NULL |
CSG |
|
XmNvalueWcs |
XmCvalueWcs |
wchar_t * |
(wchar_t *)"" |
CSG |
|
XmNverifyBell |
XmCVerifyBell |
Boolean |
dynamic |
CSG |
XmPrimitive Resource Set |
|
|
|
|
|
Name |
Class |
Type |
Default |
Access |
|
XmNbottomShadowColor |
XmCBottomShadowColor |
Pixel |
dynamic |
CSG |
|
XmNbottomShadowPixmap |
XmCBottomShadowPixmap |
Pixmap |
XmUNSPECIFIED_PIXMAP |
CSG |
|
XmNforeground |
XmCForeground |
Pixel |
dynamic |
CSG |
|
XmNhighlightColor |
XmCHighlightColor |
Pixel |
dynamic |
CSG |
|
XmNhighlightOnEnter |
XmCHighlightOnEnter |
Boolean |
False |
CSG |
|
XmNhighlightPixmap |
XmCHighlightPixmap |
Pixmap |
dynamic |
CSG |
|
XmNhighlightThickness |
XmCHighlightThickness |
Dimension |
2 |
CSG |
|
XmNnavigationType |
XmCNavigationType |
XmNavigationType |
XmNONE |
CSG |
|
XmNshadowThickness |
XmCShadowThickness |
Dimension |
2 |
CSG |
|
XmNtopShadowColor |
XmCTopShadowColor |
Pixel |
dynamic |
CSG |
|
XmNtopShadowPixmap |
XmCTopShadowPixmap |
Pixmap |
dynamic |
CSG |
|
XmNtraversalOn |
XmCTraversalOn |
Boolean |
True |
CSG |
|
XmNunitType |
XmCUnitType |
unsignedChar |
dynamic |
CSG |
|
XmNuserData |
XmCUserData |
Pointer |
NULL |
CSG |
Core Resource Set |
|
|
|
|
|
Name |
Class |
Type |
Default |
Access |
|
XmNaccelerators |
XmCAccelerators |
XtAccelerators |
NULL |
CSG |
|
XmNancestorSensitive |
XmCSensitive |
Boolean |
dynamic |
G |
|
XmNbackground |
XmCBackground |
Pixel |
dynamic |
CSG |
|
XmNbackgroundPixmap |
XmCPixmap |
Pixmap |
XmUNSPECIFIED_PIXMAP |
CSG |
|
XmNborderColor |
XmCBorderColor |
Pixel |
XtDefaultForeground |
CSG |
|
XmNborderPixmap |
XmCPixmap |
Pixmap |
XmUNSPECIFIED_PIXMAP |
CSG |
|
XmNborderWidth |
XmCBorderWidth |
Dimension |
1 |
CSG |
|
XmNcolormap |
XmCColormap |
Colormap |
dynamic |
CG |
|
XmNdepth |
XmCDepth |
int |
dynamic |
CG |
|
XmNdestroyCallback |
XmCCallback |
XtCallbackList |
NULL |
C |
|
XmNheight |
XmCHeight |
Dimension |
dynamic |
CSG |
|
XmNinitialResourcesPersistent |
XmCInitialResourcesPersistent |
Boolean |
True |
C |
|
XmNmappedWhenManaged |
XmCMappedWhenManaged |
Boolean |
True |
CSG |
|
XmNscreen |
XmCScreen |
Screen |
dynamic |
CG |
|
XmNsensitive |
XmCSensitive |
Boolean |
True |
CSG |
|
XmNtranslations |
XmCTranslations |
XtTranslations |
dynamic |
CSG |
|
XmNwidth |
XmCWidth |
Dimension |
dynamic |
CSG |
|
XmNx |
XmCPosition |
Position |
0 |
CSG |
|
XmNy |
XmCPosition |
Position |
0 |
CSG |
- XmNvalidateCallback
- Callbacks on the XmNvalidateCallback list are called
when the edits to the XbaeInput widget are activated or a losing
focus event occurs. Each callback function is passed the following
structure:
typedef struct |
|
|
{ |
|
|
|
int |
reason; |
|
XEvent |
*event; |
|
String |
pattern; |
|
String |
value; |
|
Boolean |
doit; |
} XbaeInputValidateCallbackStruct; |
|
|
- reason
- Set to XmCR_ACTIVATE if the user caused the callback
to be invoked by activating the changes in the cell or
XmCR_LOSING_FOCUS if the callback was called due to a losing focus
event.
- event
- The event pointer that triggered the callback.
- pattern
- A pointer to the pattern for the XbaeInput widget or
NULL if one does not exist. This value is provided as a
convenience to the callback.
- value
- The value as it appears in the cell at the time of the
callback being invoked.
- doit
- Indicates whether or not the value is valid. By setting
doit to False the value will not be accepted.
This callback provides the application of checking the validity of the value
entered into the
XbaeInput widget. Checking the validity of a date may
be one such instance. If the value is verified as valid, all values of the
callback may be left unchanged. If the pointer to the value is changed, the
new value will be displayed in the cell and storage for the old value
deallocated by the
XbaeInput widget. The new value's memory is owned by
the application and it is up to the application to use XtFree to deallocate
it.
If the
value is not considered valid, the
doit flag should be set
to False, forcing the user to make changes before the value can be
accepted.
Translations¶
XbaeInput inherits translations from
XmText. Some versions of
Motif do not have the
:<Key>osfInsert: |
toggle-overstrike() |
translation installed by default. If this is the case,
XbaeInput
automatically registers this translation.
Type Converters¶
XbaeInput does not define any new type converters other than the standard
type converters registered by Xt and Motif.
Public Functions¶
The following external entry points to
XbaeInput class methods are
defined:
XbaeCreateInput()
Widget XbaeCreateInput() |
|
|
|
Widget |
parent; |
|
String |
name; |
|
ArgList |
arglist; |
|
Cardinal |
argcount; |
- parent
- Specifies the parent widget ID.
- name
- Specifies the name of the created widget
- arglist
- Specifies the argument list
- argcount
- Specifies the number of attribute/value pairs in the
argument list (arglist)
XbaeCreateInput() creates an instance of an XbaeInput widget and returns
the associated widget ID.
EXAMPLE PATTERNS¶
- d[d]/d[d]/dd[dd]
- A date that would accept 1/1/99, 12/1/99, 1/12/1999,
01/01/2000, etc.
- U[L][L][L][L][L], U[L][L][L][L][L]
- "Surname, Firstname" combination, automatically
forcing correct case and allowing between 1 and 6 characters per
name.
- UU-dd[d][d]
- A flight number consisting of two uppercase letters and 2
to 4 numbers
- (ddd) ddd-dddd
- An American style phone number
- UdU[-]dUd
- A Canadian postcode with optional dash.
Virtual Bindings¶
The bindings for virtual keys are vendor specific. For information about
bindings for virtual buttons and keys, see
VirtualBindings(3X).
AUTHOR¶
Andrew Lister (lister@db.com)
RELEASE¶
This document describes XbaeInput from Xbae Version 4.9.
SEE ALSO¶
Core(3X), XmPrimitive(3X), XmText(3X)
Notice of Limitation¶
The Author, previous and current maintainers of the Xbae widgets (collectively
'authors') provide this information solely to professionals who have the
appropriate degree of experience to understand and interpret its contents in
accordance with generally accepted engineering or other professional standards
and applicable regulations. No recommendations as to products or vendors is
made or should be implied.
While the information contained herein has been prepared from sources deemed to
be reliable, the authors reserve the right to revise the information without
notice, but have no obligation to do so. Unless the recipient has been
expressly granted a license by Bellcore under separate applicable written
agreement with Bellcore, no license, expressed or implied, is granted under
any patents, copyrights or other intellectual property rights. Use of the
information is at your discretion and shall not be deemed an inducement by
Bellcore to infringe any existing or later-issued patent, copyrights or other
intellectual property right.
THE AUTHORS MAKE NO REPRESENTATIONS AND EXTENDS NO WARRANTIES, EXPRESS OR
IMPLIED, WITH RESPECT TO THE INFORMATION, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ANY PARTICULAR PURPOSE,
AND THE WARRANTY AGAINST INFRINGEMENT OF PATENTS OR OTHER INTELLECTUAL
PROPERTY RIGHTS. THE INFORMATION IS PROVIDED ``AS IS'', AND IN NO EVENT SHALL
THE AUTHORS OR ANY OF ITS AFFILIATES BE LIABLE FOR ANY DAMAGES, INCLUDING ANY
LOST PROFITS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES RELATING TO THE
INFORMATION.
Copyright 1999 Andrew Lister. All Rights Reserved.
Copyright 1999-2002 LessTif Developers
The above no warranty extends to all additions and contributions. No contributor
shall be held liable; this work is provided ``as is''. If this is a problem
for you, then don't use this software.