XbaeInput(3x)                                                    XbaeInput(3x)



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       XmCAlignmentunsigned charXmALIGNMENT_BEGINNINGCSG   |
       +------------------+-----------+------------+--------------------+-----+
       XmNautoFill        XmCBoolean  Boolean      False                CSG   |
       +------------------+-----------+------------+--------------------+-----+
       XmNconvertCase     XmCBoolean  Boolean      True                 CSG   |
       +------------------+-----------+------------+--------------------+-----+
       XmNoverwriteMode   XmCBoolean  Boolean      False                CSG   |
       +------------------+-----------+------------+--------------------+-----+
       XmNpattern         XmCString   String       NULL                 CSG   |
       +------------------+-----------+------------+--------------------+-----+
       XmNvalidateCallbackXmCCallback 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 XmCAutoShowCursorPositionBoolean       True              CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNcursorPosition         XmCCursorPosition        XmTextPosition0                 CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNeditable               XmCEditable              Boolean       True              CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNeditMode               XmCEditMode              int           XmSINGLE_LINE_EDITCSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNfocusCallback          XmCCallback              XtCallbackListNULL              CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNgainPrimaryCallback    XmCCallback              XtCallbackListNULL              CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNlosePrimaryCallback    XmCCallback              XtCallbackListNULL              CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNlosingFocusCallback    XmCCallback              XtCallbackListNULL              CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNmarginHeight           XmCMarginHeight          Dimension     5                 CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNmarginWidth            XmCMarginWidth           Dimension     5                 CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNmaxLength              XmCMaxLength             int           largest integer   CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNmodifyVerifyCallback   XmCCallback              XtCallbackListNULL              CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNmodifyVerifyCallbackWcsXmCCallback              XtCallbackListNULL              CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNmotionVerifyCallback   XmCCallback              XtCallbackListNULL              CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNsource                 XmCSource                XmTextSource  Default source    CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNtopCharacter           XmCTextPosition          XmTextPosition0                 CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNvalue                  XmCValue                 String        ""                CSG   |
       +-------------------------+------------------------+-------------+-----------------+-----+
       XmNvalueChangedCallback   XmCCallback              XtCallbackListNULL              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   |
       +--------------------+--------------------+---------------+-------------------+-----+
       XmNbottomShadowPixmapXmCBottomShadowPixmapPixmap          XmUNSPECIFIED_PIXMAPCSG   |
       +--------------------+--------------------+---------------+-------------------+-----+
       XmNforeground        XmCForeground        Pixel           dynamic             CSG   |
       +--------------------+--------------------+---------------+-------------------+-----+
       XmNhighlightColor    XmCHighlightColor    Pixel           dynamic             CSG   |
       +--------------------+--------------------+---------------+-------------------+-----+
       XmNhighlightOnEnter  XmCHighlightOnEnter  Boolean         False               CSG   |
       +--------------------+--------------------+---------------+-------------------+-----+
       XmNhighlightPixmap   XmCHighlightPixmap   Pixmap          dynamic             CSG   |
       +--------------------+--------------------+---------------+-------------------+-----+
       XmNhighlightThicknessXmCHighlightThicknessDimension       2                   CSG   |
       +--------------------+--------------------+---------------+-------------------+-----+
       XmNnavigationType    XmCNavigationType    XmNavigationTypeXmNONE              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              XtAcceleratorsNULL                CSG   |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNancestorSensitive         XmCSensitive                 Boolean       dynamic             G     |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNbackground                XmCBackground                Pixel         dynamic             CSG   |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNbackgroundPixmap          XmCPixmap                    Pixmap        XmUNSPECIFIED_PIXMAPCSG   |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNborderColor               XmCBorderColor               Pixel         XtDefaultForeground CSG   |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNborderPixmap              XmCPixmap                    Pixmap        XmUNSPECIFIED_PIXMAPCSG   |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNborderWidth               XmCBorderWidth               Dimension     1                   CSG   |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNcolormap                  XmCColormap                  Colormap      dynamic             CG    |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNdepth                     XmCDepth                     int           dynamic             CG    |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNdestroyCallback           XmCCallback                  XtCallbackListNULL                C     |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNheight                    XmCHeight                    Dimension     dynamic             CSG   |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNinitialResourcesPersistentXmCInitialResourcesPersistentBoolean       True                C     |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNmappedWhenManaged         XmCMappedWhenManaged         Boolean       True                CSG   |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNscreen                    XmCScreen                    Screen        dynamic             CG    |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNsensitive                 XmCSensitive                 Boolean       True                CSG   |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNtranslations              XmCTranslations              XtTranslationsdynamic             CSG   |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNwidth                     XmCWidth                     Dimension     dynamic             CSG   |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNx                         XmCPosition                  Position      0                   CSG   |
       +----------------------------+----------------------------+-------------+-------------------+-----+
       XmNy                         XmCPosition                  Position      0                   CSG   |
       +----------------------------+----------------------------+-------------+-------------------+-----+

   Callback Information
       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.



xbae                                4.60.4                       XbaeInput(3x)
