1XbaeInput(3x)                                                    XbaeInput(3x)
2
3
4

NAME

6       XbaeInput - The Input widget class.
7

SYNOPSIS

9       #include <Xbae/Input.h>
10

DESCRIPTION

12       XbaeInput  is  a text input field that provides generic customised data
13       entry and formatting for strings.  It does this by using a clever  XmN‐
14       modifyVerifyCallback  that is installed when the XmNpattern resource is
15       set.  The XmNpattern value may include optional characters and literals
16       which will be discussed later in this document.
17
18       The  XbaeInput  widget  is ideal for restricting data input to a digit,
19       alphanumeric character or an alphabetic character.   If  XmNconvertCase
20       is  set,  the  widget  automatically  changes  an inserted character to
21       uppercase or lowercase. Literal characters can also be included in  the
22       XmNpattern that can be automatically inserted as the user types by set‐
23       ting the XmNautofill resource to True. Optional literals cannot be auto
24       inserted, however.
25
26       Unlike  the XmText field from which this widget is subclassed, the tog‐
27       gle-overwrite action is bound to the osfInsert key.  The  XmNoverwrite‐
28       Mode  is  also provided to allow the resource to be changed programati‐
29       cally.
30
31       When the XbaeInput widget loses focus or is activated in the  same  way
32       as the XmText field would be, callbacks on the XmNvalidateCallback list
33       are invoked, allowing the programmer to validate the data  as  well  as
34       reformatting the existing string.
35
36   Classes
37       XbaeInput  inherits  behavior and resources from the Core, XmPrimitive,
38       and XmText widget classes.
39       The class pointer is xbaeInputWidgetClass.
40       The class name is XbaeInput.
41
42   New Resources
43       The following table lists the new resources defined by XbaeInput.   The
44       codes  in  the Access column indicate whether the given resource can be
45       set at creation time (C), or set by using XtSetValues (S), or retrieved
46       by using XtGetValues (G).
47
48
49       ┌──────────────────────────────────────────────────────────────────────┐
50       │                       XbaeInput Resource Set                         │
51       ├──────────────────┬───────────┬────────────┬────────────────────┬─────┤
52       │Name               │Class       │Type         │Default              │Access
53       ├──────────────────┼───────────┼────────────┼────────────────────┼─────┤
54       │XmNalignment       │XmCAlignment│unsigned char│XmALIGNMENT_BEGINNING│CSG   │
55       ├──────────────────┼───────────┼────────────┼────────────────────┼─────┤
56       │XmNautoFill        │XmCBoolean  │Boolean      │False                │CSG   │
57       ├──────────────────┼───────────┼────────────┼────────────────────┼─────┤
58       │XmNconvertCase     │XmCBoolean  │Boolean      │True                 │CSG   │
59       ├──────────────────┼───────────┼────────────┼────────────────────┼─────┤
60       │XmNoverwriteMode   │XmCBoolean  │Boolean      │False                │CSG   │
61       ├──────────────────┼───────────┼────────────┼────────────────────┼─────┤
62       │XmNpattern         │XmCString   │String       │NULL                 │CSG   │
63       ├──────────────────┼───────────┼────────────┼────────────────────┼─────┤
64       │XmNvalidateCallback│XmCCallback │Callback     │NULL                 │CSG   │
65       └T─h─i─s──r─e─s─o─u─r─c─e──h─a─s──n┴o─t──b─e─e─n──i─m─p─l┴e─m─e─n─t─e─d─.─────┴────────────────────┴─────┘
66
67
68       XmNalignment
69            This resource has not been implemented!
70
71            Specifies  the  alignment  of  the text when being edited and dis‐
72            played.  Possible  values  are  XmALIGNMENT_BEGINNINGand  XmALIGN‐
73            MENT_END.   If  XmNalignment  is  set to XmALIGNMENT_END, the text
74            will be right justified.  If  left  as  the  default  of  XmALIGN‐
75            MENT_BEGINNING, the text will be left justified.
76
77       XmNautoFill
78            The  XmNautoFill resource, when set to True, attempts to automati‐
79            cally insert a literal if a non literal is hit in an allowed  lit‐
80            eral position.  For example, if the XmNpattern resource was set up
81            to  accept  a  date  in  dd/mm/yyyy  format  and  the  user  typed
82            "18041999"  The resulting string would appear as "18/04/1999". The
83            default value is False, where the user would have to type the lit‐
84            eral.
85
86       XmNconvertCase
87            Tells the XbaeInput widget what should be done to alphabetic char‐
88            acters if the requires a lowercase or uppercase  letter.   If  the
89            XmNconvertCase  is  set  to  True (default), then the character is
90            automatically converted to the correct case.   If  set  to  False,
91            then the user must type the character in the correct case in order
92            for it to be accepted.  See the EXAMPLE PATTERNS  section  towards
93            the end of this document for some examples.
94
95       overwriteMode
96            Whether  the widget accepts characters in insert mode or overwrite
97            mode is controlled by the resource.  Setting this  resource  calls
98            the XmText toggle-overwrite() action routine, so the Motif toolkit
99            being used must also support this routine.
100
101       XmNpattern
102            The XmNpattern resource specifies  what  can  be  typed  into  the
103            XbaeInput widget.  If set to the default value of NULL any charac‐
104            ter may be entered.  The XmNpattern can be set to  a  string  con‐
105            taining the following characters.
106
107
108            a    alphabetic characters only
109            b    both - either digit or character
110            c    any character at all
111            d    digits only
112            U    upperchase character only
113            L    lowercase character only
114            [    start of optional sequence
115            ]    end of optional sequence
116            \\   escapes the next character
117            |    next char is an alternative to previous. May be chained.
118
119
120   Inherited Resources
121       The  following  table lists the resources which XbaeInput inherits from
122       it's  superclasses  XmText,  XmPrimitive  and  Core.   For  a  complete
123       description  of  each  resource,  refer to the man page for that super‐
124       class.  The codes in the "Access" column  indicate  whether  the  given
125       resource  can  be set at creation time (C), or set by using XtSetValues
126       (S), or retrieved by using XtGetValues (G).
127
128       ┌────────────────────────────────────────────────────────────────────────────────────────┐
129       │                                  XmText Resource Set                                   │
130       ├─────────────────────────┬────────────────────────┬─────────────┬─────────────────┬─────┤
131       │Name                      │Class                    │Type          │Default           │Access
132       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
133       │XmNautoShowCursorPosition │XmCAutoShowCursorPosition│Boolean       │True              │CSG   │
134       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
135       │XmNcursorPosition         │XmCCursorPosition        │XmTextPosition│0                 │CSG   │
136       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
137       │XmNeditable               │XmCEditable              │Boolean       │True              │CSG   │
138       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
139       │XmNeditMode               │XmCEditMode              │int           │XmSINGLE_LINE_EDIT│CSG   │
140       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
141       │XmNfocusCallback          │XmCCallback              │XtCallbackList│NULL              │CSG   │
142       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
143       │XmNgainPrimaryCallback    │XmCCallback              │XtCallbackList│NULL              │CSG   │
144       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
145       │XmNlosePrimaryCallback    │XmCCallback              │XtCallbackList│NULL              │CSG   │
146       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
147       │XmNlosingFocusCallback    │XmCCallback              │XtCallbackList│NULL              │CSG   │
148       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
149       │XmNmarginHeight           │XmCMarginHeight          │Dimension     │5                 │CSG   │
150       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
151       │XmNmarginWidth            │XmCMarginWidth           │Dimension     │5                 │CSG   │
152       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
153       │XmNmaxLength              │XmCMaxLength             │int           │largest integer   │CSG   │
154       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
155       │XmNmodifyVerifyCallback   │XmCCallback              │XtCallbackList│NULL              │CSG   │
156       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
157       │XmNmodifyVerifyCallbackWcs│XmCCallback              │XtCallbackList│NULL              │CSG   │
158       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
159       │XmNmotionVerifyCallback   │XmCCallback              │XtCallbackList│NULL              │CSG   │
160       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
161       │XmNsource                 │XmCSource                │XmTextSource  │Default source    │CSG   │
162       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
163       │XmNtopCharacter           │XmCTextPosition          │XmTextPosition│0                 │CSG   │
164       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
165       │XmNvalue                  │XmCValue                 │String        │""                │CSG   │
166       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
167       │XmNvalueChangedCallback   │XmCCallback              │XtCallbackList│NULL              │CSG   │
168       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
169       │XmNvalueWcs               │XmCvalueWcs              │wchar_t *     │(wchar_t *)""     │CSG   │
170       ├─────────────────────────┼────────────────────────┼─────────────┼─────────────────┼─────┤
171       │XmNverifyBell             │XmCVerifyBell            │Boolean       │dynamic           │CSG   │
172       └─────────────────────────┴────────────────────────┴─────────────┴─────────────────┴─────┘
173       ┌───────────────────────────────────────────────────────────────────────────────────┐
174       │                             XmPrimitive Resource Set                              │
175       ├────────────────────┬────────────────────┬───────────────┬───────────────────┬─────┤
176       │Name                 │Class                │Type            │Default             │Access
177       ├────────────────────┼────────────────────┼───────────────┼───────────────────┼─────┤
178       │XmNbottomShadowColor │XmCBottomShadowColor │Pixel           │dynamic             │CSG   │
179       ├────────────────────┼────────────────────┼───────────────┼───────────────────┼─────┤
180       │XmNbottomShadowPixmap│XmCBottomShadowPixmap│Pixmap          │XmUNSPECIFIED_PIXMAP│CSG   │
181       ├────────────────────┼────────────────────┼───────────────┼───────────────────┼─────┤
182       │XmNforeground        │XmCForeground        │Pixel           │dynamic             │CSG   │
183       ├────────────────────┼────────────────────┼───────────────┼───────────────────┼─────┤
184       │XmNhighlightColor    │XmCHighlightColor    │Pixel           │dynamic             │CSG   │
185       ├────────────────────┼────────────────────┼───────────────┼───────────────────┼─────┤
186       │XmNhighlightOnEnter  │XmCHighlightOnEnter  │Boolean         │False               │CSG   │
187       ├────────────────────┼────────────────────┼───────────────┼───────────────────┼─────┤
188       │XmNhighlightPixmap   │XmCHighlightPixmap   │Pixmap          │dynamic             │CSG   │
189       ├────────────────────┼────────────────────┼───────────────┼───────────────────┼─────┤
190       │XmNhighlightThickness│XmCHighlightThickness│Dimension       │2                   │CSG   │
191       ├────────────────────┼────────────────────┼───────────────┼───────────────────┼─────┤
192       │XmNnavigationType    │XmCNavigationType    │XmNavigationType│XmNONE              │CSG   │
193       ├────────────────────┼────────────────────┼───────────────┼───────────────────┼─────┤
194       │XmNshadowThickness   │XmCShadowThickness   │Dimension       │2                   │CSG   │
195       ├────────────────────┼────────────────────┼───────────────┼───────────────────┼─────┤
196       │XmNtopShadowColor    │XmCTopShadowColor    │Pixel           │dynamic             │CSG   │
197       ├────────────────────┼────────────────────┼───────────────┼───────────────────┼─────┤
198       │XmNtopShadowPixmap   │XmCTopShadowPixmap   │Pixmap          │dynamic             │CSG   │
199       ├────────────────────┼────────────────────┼───────────────┼───────────────────┼─────┤
200       │XmNtraversalOn       │XmCTraversalOn       │Boolean         │True                │CSG   │
201       ├────────────────────┼────────────────────┼───────────────┼───────────────────┼─────┤
202       │XmNunitType          │XmCUnitType          │unsignedChar    │dynamic             │CSG   │
203       ├────────────────────┼────────────────────┼───────────────┼───────────────────┼─────┤
204       │XmNuserData          │XmCUserData          │Pointer         │NULL                │CSG   │
205       └────────────────────┴────────────────────┴───────────────┴───────────────────┴─────┘
206       ┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
207       │                                       Core Resource Set                                         │
208       ├────────────────────────────┬────────────────────────────┬─────────────┬───────────────────┬─────┤
209       │Name                         │Class                        │Type          │Default             │Access
210       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
211       │XmNaccelerators              │XmCAccelerators              │XtAccelerators│NULL                │CSG   │
212       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
213       │XmNancestorSensitive         │XmCSensitive                 │Boolean       │dynamic             │G     │
214       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
215       │XmNbackground                │XmCBackground                │Pixel         │dynamic             │CSG   │
216       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
217       │XmNbackgroundPixmap          │XmCPixmap                    │Pixmap        │XmUNSPECIFIED_PIXMAP│CSG   │
218       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
219       │XmNborderColor               │XmCBorderColor               │Pixel         │XtDefaultForeground │CSG   │
220       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
221       │XmNborderPixmap              │XmCPixmap                    │Pixmap        │XmUNSPECIFIED_PIXMAP│CSG   │
222       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
223       │XmNborderWidth               │XmCBorderWidth               │Dimension     │1                   │CSG   │
224       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
225       │XmNcolormap                  │XmCColormap                  │Colormap      │dynamic             │CG    │
226       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
227       │XmNdepth                     │XmCDepth                     │int           │dynamic             │CG    │
228       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
229       │XmNdestroyCallback           │XmCCallback                  │XtCallbackList│NULL                │C     │
230       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
231       │XmNheight                    │XmCHeight                    │Dimension     │dynamic             │CSG   │
232       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
233       │XmNinitialResourcesPersistent│XmCInitialResourcesPersistent│Boolean       │True                │C     │
234       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
235       │XmNmappedWhenManaged         │XmCMappedWhenManaged         │Boolean       │True                │CSG   │
236       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
237       │XmNscreen                    │XmCScreen                    │Screen        │dynamic             │CG    │
238       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
239       │XmNsensitive                 │XmCSensitive                 │Boolean       │True                │CSG   │
240       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
241       │XmNtranslations              │XmCTranslations              │XtTranslations│dynamic             │CSG   │
242       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
243       │XmNwidth                     │XmCWidth                     │Dimension     │dynamic             │CSG   │
244       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
245       │XmNx                         │XmCPosition                  │Position      │0                   │CSG   │
246       ├────────────────────────────┼────────────────────────────┼─────────────┼───────────────────┼─────┤
247       │XmNy                         │XmCPosition                  │Position      │0                   │CSG   │
248       └────────────────────────────┴────────────────────────────┴─────────────┴───────────────────┴─────┘
249
250   Callback Information
251       XmNvalidateCallback
252            Callbacks on the XmNvalidateCallback  list  are  called  when  the
253            edits  to  the  XbaeInput  widget  are activated or a losing focus
254            event occurs.  Each callback  function  is  passed  the  following
255            structure:
256
257
258            typedef struct
259            {
260                    int           reason;
261                    XEvent        *event;
262                    String        pattern;
263                    String        value;
264                    Boolean       doit;
265            } XbaeInputValidateCallbackStruct;
266
267
268            reason    Set  to XmCR_ACTIVATE if the user caused the callback to
269                      be invoked by activating the  changes  in  the  cell  or
270                      XmCR_LOSING_FOCUS  if  the  callback was called due to a
271                      losing focus event.
272
273            event     The event pointer that triggered the callback.
274
275            pattern   A pointer to the pattern for  the  XbaeInput  widget  or
276                      NULL if one does not exist.  This value is provided as a
277                      convenience to the callback.
278
279            value     The value as it appears in the cell at the time  of  the
280                      callback being invoked.
281
282            doit      Indicates whether or not the value is valid.  By setting
283                      doit to False the value will not be accepted.
284
285            This callback provides the application of checking the validity of
286            the  value entered into the XbaeInput widget.  Checking the valid‐
287            ity of a date may be one such instance.  If the value is  verified
288            as  valid,  all  values of the callback may be left unchanged.  If
289            the pointer to the value is changed, the new value  will  be  dis‐
290            played  in  the  cell and storage for the old value deallocated by
291            the XbaeInput widget.  The new value's  memory  is  owned  by  the
292            application and it is up to the application to use XtFree to deal‐
293            locate it.
294
295            If the value is not considered valid, the doit flag should be  set
296            to False, forcing the user to make changes before the value can be
297            accepted.
298
299   Translations
300       XbaeInput inherits translations from XmText.  Some versions of Motif do
301       not have the
302
303       :<Key>osfInsert:           toggle-overstrike()
304
305
306       translation installed by default.  If this is the case, XbaeInput auto‐
307       matically registers this translation.
308
309   Type Converters
310       XbaeInput does not define any new type converters other than the  stan‐
311       dard type converters registered by Xt and Motif.
312
313   Public Functions
314       The  following  external  entry  points  to XbaeInput class methods are
315       defined:
316
317       XbaeCreateInput()
318
319              Widget XbaeCreateInput()
320                  Widget     parent;
321                  String     name;
322                  ArgList    arglist;
323                  Cardinal   argcount;
324
325
326              parent    Specifies the parent widget ID.
327
328              name      Specifies the name of the created widget
329
330              arglist   Specifies the argument list
331
332              argcount  Specifies the number of attribute/value pairs  in  the
333                        argument list (arglist)
334
335              XbaeCreateInput() creates an instance of an XbaeInput widget and
336              returns the associated widget ID.
337
338   EXAMPLE PATTERNS
339       d[d]/d[d]/dd[dd]
340            A date that would accept 1/1/99, 12/1/99,  1/12/1999,  01/01/2000,
341            etc.
342
343       U[L][L][L][L][L], U[L][L][L][L][L]
344            "Surname,  Firstname"  combination,  automatically forcing correct
345            case and allowing between 1 and 6 characters per name.
346
347       UU-dd[d][d]
348            A flight number consisting of two uppercase letters  and  2  to  4
349            numbers
350
351       (ddd) ddd-dddd
352            An American style phone number
353
354       UdU[-]dUd
355            A Canadian postcode with optional dash.
356
357   Virtual Bindings
358       The  bindings  for  virtual  keys  are vendor specific. For information
359       about bindings for virtual buttons and keys, see VirtualBindings(3X).
360

AUTHOR

362       Andrew Lister (lister@db.com)
363
364

RELEASE

366       This document describes XbaeInput from Xbae Version 4.9.
367

SEE ALSO

369       Core(3X), XmPrimitive(3X), XmText(3X)
370

Notice of Limitation

372       The Author, previous and current maintainers of the Xbae widgets  (col‐
373       lectively  'authors')  provide this information solely to professionals
374       who have the appropriate degree of experience to understand and  inter‐
375       pret  its contents in accordance with generally accepted engineering or
376       other professional standards and applicable regulations. No recommenda‐
377       tions as to products or vendors is made or should be implied.
378
379       While  the  information contained herein has been prepared from sources
380       deemed to be reliable, the authors reserve  the  right  to  revise  the
381       information without notice, but have no obligation to do so. Unless the
382       recipient has been expressly granted a license by Bellcore under  sepa‐
383       rate  applicable written agreement with Bellcore, no license, expressed
384       or implied, is granted under any patents, copyrights or other intellec‐
385       tual  property rights. Use of the information is at your discretion and
386       shall not be deemed an inducement by Bellcore to infringe any  existing
387       or  later-issued  patent,  copyrights  or  other  intellectual property
388       right.
389
390       THE AUTHORS MAKE NO REPRESENTATIONS AND EXTENDS NO WARRANTIES,  EXPRESS
391       OR IMPLIED, WITH RESPECT TO THE INFORMATION, INCLUDING, BUT NOT LIMITED
392       TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ANY  PAR‐
393       TICULAR  PURPOSE,  AND  THE WARRANTY AGAINST INFRINGEMENT OF PATENTS OR
394       OTHER INTELLECTUAL PROPERTY RIGHTS. THE INFORMATION  IS  PROVIDED  ``AS
395       IS'',  AND  IN  NO  EVENT SHALL THE AUTHORS OR ANY OF ITS AFFILIATES BE
396       LIABLE FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS OR OTHER  INCIDENTAL
397       OR CONSEQUENTIAL DAMAGES RELATING TO THE INFORMATION.
398
399       Copyright 1999 Andrew Lister.  All Rights Reserved.
400       Copyright 1999-2002 LessTif Developers
401
402
403
404       The  above  no warranty extends to all additions and contributions.  No
405       contributor shall be held liable; this work is provided ``as is''.   If
406       this is a problem for you, then don't use this software.
407
408
409
410xbae                                4.60.4                       XbaeInput(3x)
Impressum