Counter Widget

Classname: xwcounterWidgetClass

Description:

The Counter Widget displays numbers, incrementing (or decrementing) them by two arrow buttons, cursor keys or moving the mouse with pressed left button. It might be editable to type in new numbers. The contents my be read using callbacks and the associated callbackstructure, or via convenience functions. It allows three formats, the default format is int. The others are float and Hex numbers. Except setting float numbers, the value may be set using the normal XtSelArgs method, whereas float numbers need a special conversion function. (XtSetArg is casting the given value to int, in case of float a memcpy is needed). Internally all type conversions are done by the Widget. Setting value limits and doing checks on typed values make it safe in use. The increment may be set to any legal number.

Two examples, the left one displaying Hex values, the right floating point numbers:

Resources:

The widget includes the »core« , "Composite", "Constraint" and "XmManager" class with all resources. To describe the features of the Counter widget, it has several resources for it's own. The following table contains the resource-name, the resource-class and the accesstype. Defining the resource in a general resourcefile file like .Xdefaults, means, leave out the prefix XwN or XwC. The access type defines, if the resource may be set at creation »C«, using XtSetValues »S«, only at creation using XtSetArg »CS« and being read using XtGetValues »G«.

Detailed Description of special Resources

Callbacks:

Possible callbacks are:

XmNdestroyCallback XmNfocusCallback, XmNlosingFocusCallback, XmNvalueChangedCallback, XmNactivateCallback.
Of course the most important is the value changed callback. It is called at any value change, so the user may react directly on the change. (p.e. Move a displayed item). Activate and loosing focus are used to get the last value back. The delivered callback data structure is the same for all four callbacks:

typedef struct{

int reason;

XEvent *event;

int format;

union{

float fvalue;

int ivalue;

}value;

} xwcounterCallbackStruct;

The item "format" should be used to decide, which part of the union is to be used. As Counter stores the value type dependent, it returns it type dependent.

XmNcolumns, XwNtextBackground, XmNmarginHeight, XmNmarginWidth, XmNmaxLength, XmNfontList

These resources are used for the embedded textwidget, (see XmText)

XmNeditable

If True, allows the user to type the new value directly in.

XmNverifyBell

Acoustic warning, if wrong characters are typed.

XmNminimum, XmNmaximum

For Int and Float Format, these given limits are checked. The value won't be set beyond the limits. In case of Hex format, the limits are set internally to maximum positive/maximum negative. If Float format is used, use "xwcounterFloatToXtArgVal" to set the value.

XmNFormat

This is the most important resource. It defines the handling type of numbers. As it switches internal structures and behaviour, it can be set ONLY at creation time.

Possible formats are : XwFloat , XwInt , XwHex

XmNdecimalPoints

In case of Float format the number of digits behind the decimal point is defined.

XmNincrement

Incrementing or decrementing can be set to any value. If Float format is used, use "xwcounterFloatToXtArgVal" to set the value

XmNvalue

Setting a new (or the initial value). If Float format is used, use "xwcounterFloatToXtArgVal" to set the value. To set the actual value, a convenience function might be used. Getting the actual value, convenience functions depending on format are available.

Convenience Functions:

Name: XgCreateCounter
Header file: »Counter.h«

Widget XgCreateCounter(Widget, char *, ArgList, Cardinal);

XwCreateCounter creates a widgetinstance of class xwcounterWidgetClass and returns the widget-id. The argumentlist follows the general standard.

Name: XtArgVal xwCounterFloatToXtArgVal

Header file: »Counter.h«

XtArgVal xwCounterFloatToXtArgVal (double value);

This function overrides the behaviour of XtSetArgs to cast the value into and int. It does a memcpy, passing the pointer to the widget. This is now handled internally.

Name: xwCounterSetValue

Header file: »Counter.h«

Boolean xwCounterSetValue(Widget w, double value);

Setting the actual value can be done using the normal XtSetArgs sequence or this function. Don't worry about the double argument, other types are converted .

Name: xwCounterGetFValue , xwCounterGetIValue

Header file: »Counter.h«

float xwCounterGetFValue(Widget w);

int xwCounterGetIValue(Widget w);

Two functions to retrieve the actual value.