I_FLDMOD

Modify an input field’s attributes at runtime

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall I_FLDMOD(window_id, field_spec, [length], [type][, qualifier, …])

Arguments

window_id

The ID of the input window containing the field to be modified. (n)

field_spec

The specification for the field whose attributes I_FLDMOD will modify. See Field specifications for information. (a)

length

(optional) The maximum input length. Use length to shorten a field or re‑lengthen a field after it has been shortened. The modified length must be greater than zero and less than or equal to the original length. (n)

type

(optional) The requested field type. Duplicates D_FLD_TYPE; see Type and D_FLD_TYPE. (n)

qualifier

(optional) One or more of the field qualifiers shown in the Field qualifiers table. (a or n)

Discussion

I_FLDMOD modifies various input field attributes at runtime. You can use I_FLDMOD to change the fields in your current input set. Note that I_FLDMOD changes only the field’s display, not the internal input buffer layout. In order to prevent invalid data, field_spec is always initialized, so alterations to the displayed data are reflected on the next input or display.

Note

I_FLDMOD’s options are also available with the .FIELD script command. For more detailed information on I_FLDMOD options, see the corresponding qualifier in .FIELD qualifiers.

If either window_id or field_spec is invalid, a fatal error occurs. Any D_FLD_xxx argument flag not listed above will result in the fatal error “Invalid I_FLDMOD code (code),” where code is the invalid value passed. If you specify a qualifier (other than D_FLD_DEC) that does not apply to the field’s destination type, it is ignored.

You can specify methods with the following qualifiers even if the field did not originally define them: D_FLD_ARRIVE, D_FLD_CHANGE, D_FLD_DISPLAY, D_FLD_DRILL, D_FLD_EDITFMT, D_FLD_HYPERLINK, D_FLD_LEAVE.

For all the qualifiers that have text string arguments (such as D_FLD_USER), you can only specify a string that is equal to or shorter than the original text string. If you shorten the length, you can re‑lengthen or restore the text string for the field as long as it doesn’t exceed the length of the original string; if it does exceed the original length, the modification will be ignored.

User‑defined field methods are passed the user type and user text strings as arguments. Thus, it is important to know the order in which methods are invoked if the developer modifies either of these strings within a method. The input field methods are invoked in the following order: arrive method, EEDTDSP_METHOD, %IEDITFMT_METHOD, ECHKFLD_METHOD, change method, EDSPFLD_METHOD or %IDISPLAY_METHOD, leave method, and drill or hyperlink method.

The default qualifiers are also inspected when arriving upon the field so the default value can be displayed. Thus, modifying the default value within a method (other than the arrive method) will not cause that new default value to be used if the user presses enter.

Because the information line is displayed when arriving on a field, modifying a field’s information line within a method (other than the arrive method) may not take visible effect until the next time the field is arrived upon. Otherwise, to immediately affect the information line, use either E_SECT to modify it or %M_SIGNAL to exit the method and force the arrival on the field to occur again.

Field qualifiers

Qualifier and arguments

Description

D_FLD_DEC, num_places

Decimal places.

D_FLD_SIZE, storage_size

Storage size. See D_FLD_SIZE for size limits.

D_FLD_TYPE, type

Field type. See Type and D_FLD_TYPE.

D_ON

Turn on one or more of the following field qualifiers. See D_ON and D_OFF for details. (default)

D_OFF

Turn off one or more of the following field qualifiers. When qualifiers are preceded by D_OFF, flags that normally require an argument do not. See D_ON and D_OFF for details.

D_FLD_ARRIVE, arrive_method

Arrive method.

D_FLD_ATTR, attribute

Attributes. See D_FLD_ATTR for valid values for attribute.

D_FLD_AUTO

Automatic input.

D_FLD_BREAK

Break on change.

D_FLD_BRK_ALWAYS

Break always.

D_FLD_BRK_RTRN

Break on return only.

D_FLD_BZRO

Blank if zero.

D_FLD_CHANGE, change_method

Change method.

D_FLD_CHECKBOX

Check box field.

D_FLD_COLOR, palette#

Color.

D_FLD_COPY

Copy default.

D_FLD_DATE, date_type

Date format. See D_FLD_DATE for valid values for date_type.

D_FLD_DECR

Decrement default.

D_FLD_DISABLED

Disabled.

D_FLD_DISPLAY, display_method

Display method.

D_FLD_DFLT, string

Default entry.

D_FLD_DRILL, drill_method

Drill method.

D_FLD_DSPLEN, display_len

Display length. Cannot be specified for check boxes, radio buttons, selection windows, or multi‑line fields.

D_FLD_EDITFMT, editfmt_method

Edit format method.

D_FLD_ENUM, [dlen],[base],[step]

Enumeration properties. See D_FLD_ENUM.

D_FLD_FMT, string

Format string.

D_FLD_FONT, font_id

Field font. See D_FLD_FONT and D_FLD_PROMPTFONT for valid values for font_id.

D_FLD_FPOS [, D_CHANGE], row, col

Field position. See D_FLD_FPOS and D_FLD_POS.

D_FLD_HELP, string

Help identifier.

D_FLD_HYPERLINK, hyper_method

Hyperlink method.

D_FLD_INCR

Increment default.

D_FLD_INFO, string

Information text.

D_FLD_INPLEN, input_len

Maximum input length. Cannot be specified for check boxes, radio buttons, selection windows, or multi‑line fields.

D_FLD_JUST, just_flag

Justification, where just_flag is D_JST_CENTER, D_JST_LEFT, or D_JST_RIGHT.

D_FLD_LEAVE, leave_method

Leave method.

D_FLD_NEG

Negative allowed.

D_FLD_NEGONLY

Negative allowed only.

D_FLD_NEGORZERO

Negative or zero allowed only.

D_FLD_NODEC

No decimal required.

D_FLD_NOECHO

No echo.

D_FLD_NOECHR, char

Fill character when D_FLD_NOECHO is specified (otherwise ignored).

D_FLD_NOTERM

No termination.

D_FLD_PAINT, char

Paint character.

D_FLD_POS [, D_CHANGE], row, col

Prompt position. See D_FLD_FPOS and D_FLD_POS.

D_FLD_PROMPTFONT, font_id

Prompt font. See D_FLD_FONT and D_FLD_PROMPTFONT for valid values for font_id.

D_FLD_RADIO

Radio buttons.

D_FLD_RANGE, min, max

Range. See D_FLD_RANGE.

D_FLD_READONLY

Read‑only. Not valid for check boxes, radio buttons, selection lists and windows. See D_FLD_READONLY.

D_FLD_REQUIRED

Required input.

D_FLD_RETPOS

Retain position in text field.

D_FLD_TIME, time_type

Time format. See D_FLD_TIME for valid values for time_type.

D_FLD_TIMESTAMP, format

Timestamp. See D_FLD_TIMESTAMP for details on this option and valid values for format.

D_FLD_UC

Uppercase only.

D_FLD_USER, string

User‑defined text string.

D_FLD_VIEWLEN, view_length

The width of the field (i.e., the width of the area on the screen that will display data for the field). Cannot be specified for check boxes or radio buttons.

D_FLD_WAIT, wait_time

Input time‑out for the field, where wait_time is the number of seconds to wait or one of the options shown in D_FLD_WAIT.

Type and D_FLD_TYPE

Type is retained for compatibility with earlier versions of Toolkit. It duplicates the functionality of D_FLD_TYPE, except that it does not support D_USERTYPE. A user‑defined field can only be specified using D_FLD_TYPE.

Type and D_FLD_TYPE supports the following options for type:

D_ALPHA

Alphanumeric

D_DECIMAL

Decimal

D_INTEGER

Integer

D_NUMERIC

Numeric (same as decimal)

D_USERTYPE, type_string

User‑defined

I_FLDMOD will change the field type between alpha, decimal, and integer; requests to change to or from text fields will be ignored.

If you change the field type from alpha, the following defaults apply unless you override them:

If you change the field type to alpha, the following defaults apply unless you override them:

If you change the field type to D_INTEGER, the storage size is changed to the nearest (but not larger) valid integer storage size. Valid sizes are 1, 2, 4, or 8. Integer fields support all qualifiers that are valid for decimal fields without precision.

If you want the field to become an implied‑decimal field, you can pass D_FLD_DEC, num_places as a qualifier. Regardless of its original setting, any field type can be converted to implied‑decimal. Note that you can specify up to nine digits after the decimal point.

D_ON and D_OFF

The D_ON and D_OFF codes indicate whether the field qualifiers that follow in the argument list are to be turned on or off. D_ON is the default state for any qualifiers listed.

When qualifiers are preceded by D_OFF, flags that normally require an argument do not. For example, the first I_FLDMOD call below turns no echo on. The second call turns it off.

xcall i_fldmod(inpid, "myfield",,, D_FLD_NOECHR, '*')
xcall i_fldmod(inpid, "myfield",,, D_OFF, D_FLD_NOECHR)

Turning off D_FLD_BRK, D_FLD_BRK_ALWAYS, or D_FLD_BRK_RTRN results in a field with no break.

D_FLD_ATTR

D_FLD_ATTR accepts the following values for attribute (defined in tools.def):

A_ALL

All attributes (same as A_BHRU)

A_NONE

No attributes

A_B | A_I

Blinking (UNIX and OpenVMS) or italic (Windows).
“I” can be substituted whenever “B” appears in the following flags.

A_BH

Blinking, highlighted

A_BHR

Blinking, highlighted, reverse

A_BHRU

Blinking, highlighted, reverse, underlined

A_BHU

Blinking, highlighted, underlined

A_BR

Blinking, reverse

A_BRU

Blinking, reverse, underlined

A_BU

Blinking, underlined

A_H

Highlighted

A_HR

Highlighted, reverse

A_HRU

Highlighted, reverse, underlined

A_HU

Highlighted, underlined

A_R

Reverse

A_RU

Reverse, underlined

A_U

Underlined

D_FLD_DATE

D_FLD_DATE accepts the following values for date_type:

D_DATE_Y2J

YYJJJ date format

D_DATE_Y2MD

YYMMDD date format

D_DATE_Y2P

YYPP date format

D_DATE_Y4J

YYYJJJ date format

D_DATE_Y4MD

YYYYMMDD date format

D_DATE_Y4P

YYYYPP date format

To make the field default to the today’s date, add D_DATE_TODAY to any of the above. For a short date, add D_DATE_SHORT to any of the above. (You can add both of these if desired,)

D_FLD_ENUM

To use D_FLD_ENUM, the field must already be an enumerated field. You cannot use this to turn a non‑enumerated field into an enumerated field, and you cannot use D_OFF with this qualifier to change an enumerated field into a non‑enumerated field. (D_OFF causes D_FLD_ENUM to be ignored.)

A display length (dlen) set with D_FLD_ENUM overrides any previously specified display length (for example, any display length set with D_FLD_DSPLEN).

When using D_FLD_ENUM, you must include all comma placeholders for the arguments (even those you don’t pass) unless this is the last qualifier for the I_FLDMOD call, in which case you must include only the comma placeholders that precede the last argument specified for D_FLD_ENUM. If you omit an argument, the corresponding enumeration property will remain unchanged.

D_FLD_FONT and D_FLD_PROMPTFONT

The font_id argument to D_FLD_FONT and D_FLD_PROMPTFONT can be the name of a font palette entry, a font handle, or one of the following:

DF_ALTERNATE

Alternate font

DF_CURRENT

Current font

DF_DEBUGGER

Debugger font

DF_DEFAULT

Global font

If you change the type of a field (for example, alpha to numeric) and you are using any of the FONT_ initialization settings, be aware that the corresponding font isn’t automatically applied. To update the font, use D_FLD_FONT. (Note that if a view length is specified on Windows, changing the font may change the width of the field. See VIEW_LENGTH, NOVIEW_LENGTH for information.)

Because a list has only one font setting, using I_FLDMOD to change the font for a field in a list has no effect. With the ActiveX Toolkit list, however, you can manipulate the font for individual cells by using the API Extension methods SetCellFont, Set headerCellFont, and SetFooterCellFont.

Note

On Windows, do not use I_FLDMOD to change font settings for a column in a Toolkit list or an ActiveX implementation of a Toolkit list. This doesn’t work on Windows: the font will revert to the standard typeface and size, and data in the column will be blanked out. This is because input field fonts are not applied to lists. For an ActiveX Toolkit list, you can use the SetCellFont method to change the font of a specific cell.

I_FLDMOD settings for an ActiveX Toolkit list will not override cell‑level fonts or colors specified by the SetCellFont and SetCellColor ActiveX Toolkit list methods.

D_FLD_FPOS and D_FLD_POS

D_FLD_POS modifies the position of the prompt only. It does not affect the field’s position (unlike changing the default field position for IB_FIELD or .FIELD). To modify the field position, you must use D_FLD_FPOS. You must also use D_FLD_FPOS to modify the position of a check box prompt on Windows because the position of a check box’s prompt is determined by its field position. If either position places any part of a field or prompt outside the window, the positions are automatically adjusted so that the field and prompt fit in the window.

D_FLD_RANGE

D_FLD_RANGE can be specified only for input fields that had a range originally, either using the RANGE qualifier in Script, or using IB_FIELD’s D_FLD_RANGE. The field must be numeric, and min and max must not exceed the field’s storage size. If you use variables for beg and end, they must be alpha variables; decimal variables will not work.

D_FLD_READONLY

If you use D_FLD_READONLY for a field that can’t be set to read‑only (i.e., a check box, a radio button set, or a field with a selection list or a selection window), the read‑only setting will be accepted, but it won’t affect the field. (For these field types, use I_DISABLE rather than I_READONLY.) However, if the field is subsequently changed to a regular text field, Toolkit may use this setting because when a field is changed to a text field, the most recent read‑only state setting is used to determine whether the field will be read‑only or read/write.

Tip

You can also set a field’s read‑only state with I_READONLY. For information on the differences between D_FLD_READONLY and I_READONLY, see I_READONLY.

For information on changing read‑only settings from an input method for the field, see Notes on input methods.

D_FLD_SIZE

Alpha and alpha arrayed fields can have up to 65,535 characters. Decimal fields (including implied decimal fields) have a maximum size of 28, and for implied‑decimal fields, up to 28 digits can follow the decimal point. Integer fields on any operating system can have 1, 2, 4, or 8 digits, depending on size.

D_FLD_TIME

D_FLD_TIME accepts the following values for time_type:

D_TIME_HM

HHMM time format

D_TIME_HMS

HHMMSS time format

To make the field default to the current time, add D_TIME_NOW to either of the above. To add AM/PM to the display, add D_TIME_AMPM to either of the above. (You can add both of these if desired.)

D_FLD_TIMESTAMP

If D_OFF is in effect, D_FLD_TIMESTAMP changes a timestamp field to a standard read‑only 8‑byte integer field. Do not use the format argument when D_OFF is in effect. (It will be interpreted as another qualifier.)

If D_ON is in effect, D_FLD_TIMESTAMP must be followed by the format argument, which enables you to change the formatting used for a timestamp field. The format argument can be one or both of the following, or 0 (for neither):

D_TIMESTAMP_AMPM

Use 12‑hour notation and AM/PM designation

D_TIMESTAMP_SHORT

Use short display format (no century, seconds, or milliseconds)

To specify both D_TIMESTAMP_AMPM and D_TIMESTAMP_SHORT, use the bitwise OR operator (.BOR. or |) or add them. If a flag isn’t passed, it will be reset to its default value. For example, if you don’t pass D_TIMESTAMP_SHORT, the long display format will be used even if the field was previously set to use the short format.

For D_ON, D_FLD_TYPE must be set to D_INTEGER, and the field must be a read‑only, 8‑byte integer. It cannot be a selection field, a radio button set, or a check box. Otherwise, an error will occur.

D_FLD_WAIT

The wait_time argument to D_FLD_WAIT can be the number of seconds to wait or one of the following:

D_FOREVER or ‑1

Wait until I/O processing is completed

D_GLOBAL or ‑2

Use the globally specified time‑out

D_IMMEDIATE or 0

Time out immediately

See also

Examples

The following is a sample interface for a room scheduler. This program assumes two different companies in the same building use this scheduler. Company Alpha likes to describe all of its rooms with an alpha field, such as “Conference room,” “Laboratory,” and “Break room.” Company Numeric, however, prefers to use room numbers that are no larger than 9999. Company Alpha does not allow a blank room name, but Company Numeric allows a room #0.

The first field in this input window asks whether Company Alpha or Company Numeric is entering the schedule, and it modifies the room field accordingly.

.include "WND:tools.def"
record
  id                    ,i4
  colid                 ,i4

record data
  company               ,a30
  room                  ,a20
  time                  ,a5
  ampm                  ,a2
proc
;Set up stuff 
xcall u_start("rmsched") 
xcall i_ldinp(id, g_utlib, "rmsched") 
;Start input processing 
do forever
  begin
    xcall i_input(id,, data)
    if (g_setsts) then              ;At company break field
      begin
        if (company .eq. "Numeric Company") then
          xcall i_fldmod(id, "room", 4, D_NUMERIC, D_OFF, D_FLD_REQUIRED) 
        else
          xcall i_fldmod(id, "room", 20, D_ALPHA, D_ON, D_FLD_REQUIRED)
      end
    else
      begin                         ;Process the input
        xcall i_init(id)
      end
  end                               ;End of "do forever"
xcall u_finish
.end

The input window looks like this:

.input rmsched, 10, 65
.field company, a30, req, break, prompt("Company Name  "),–
      sel(0, 30, 2, "Alpha Company", "Numeric Company")
.field room, a20, pos(2, 9), prompt("Room   ")
.field time, d5, pos(3, 9), prompt("Time   "), format("ZX:XX")
.field ampm, a2, sel(0, 2, 2, "am", "pm"), pos(change, 0, 1)
.end

The following example changes the custno field to type alpha, with uppercase input only.

xcall i_fldmod(inpid, "custno",,, D_FLD_TYPE, D_ALPHA, D_FLD_UC)

The next example removes the “required” status from the field creditref.

xcall i_fldmod(inpid, "creditref",,, D_OFF, D_FLD_REQUIRED)

The following example modifies the field date to default to today’s date.

xcall i_fldmod(inpid, "date",,, D_FLD_DATE, D_DATE_Y4MD+D_DATE_TODAY)