%IDISPLAY_METHOD

Perform input field display processing

function IDISPLAY_METHOD,^val
   a_data_stored        ,a
   a_data_displayed     ,a
   a_inpinfo            ,a
   a_inprec             ,a
   a_attributes         ,n
   a_color              ,n
   a_methoddata1        ,any
         .
         .
   a_methoddata20       ,any

Return value

%IDISPLAY_METHOD returns true to display and false to not display the contents of a_data_displayed into the field. (n)

Arguments

a_data_stored

A buffer for the final storage of the data that’s about to be displayed. (a)

a_data_displayed

A buffer for the display form of the data. (a)

a_inpinfo

The structure of input information. (a)

a_inprec

(optional) The data_area argument (or the data_location argument for I_INPFLD on Windows) passed to the calling input routine. This is not passed if the calling routine is I_DSPFLD. And on UNIX and OpenVMS, it is not passed if the calling routine is I_INPFLD. (a)

a_attributes

The attribute to apply to the data displayed. One of the following flags defined in tools.def: (n)

A_NONE = No attributes.

A_U = Underlined.

A_R = Reverse.

A_RU = Reverse, underlined.

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

A_BU = Blinking, underlined.

A_BR = Blinking, reverse.

A_BRU = Blinking, reverse, underlined.

A_H = Highlighted.

A_HU = Highlighted, underlined.

A_HR = Highlighted, reverse.

A_HRU = Highlighted, reverse, underlined.

A_BH = Blinking, highlighted.

A_BHU = Blinking, highlighted, underlined.

A_BHR = Blinking, highlighted, reverse.

A_BHRU = Blinking, highlighted, reverse, underlined.

A_ALL = All attributes (same as A_BHRU).

a_color

The color to apply to the data displayed, where a_color is a palette number in the range 1 to 16. (n)

a_methoddata1 through a_methoddata20

(optional) Up to 20 additional data arguments. (any)

Discussion

%IDISPLAY_METHOD is a function you write and name when you want your program to display data differently from how Toolkit will display it. This method is called after Toolkit has formatted the display according to its rules, thus overriding or adding to Toolkit’s functionality.

This function is called by I_INPUT, I_INPFLD, I_DISPLAY, and I_DSPFLD when a display method is specified for the field being processed. You can specify a display method for the field by using the DISPLAY_METHOD qualifier in a .FIELD script command or the D_FLD_DISPLAY option in I_FLDMOD or IB_FIELD.

%IDISPLAY_METHOD is called only after the new field contents have been subjected to all the specified Toolkit display logic. %IDISPLAY_METHOD has the “last chance” opportunity to override or add to the Toolkit’s functionality.

If a view length has been specified for a field, make sure your display method allows Toolkit to perform the final display—rather than displaying the data within your display method and returning false to prevent Toolkit from displaying it. The display method should only format the data for Toolkit to display and then return true.

The inpinf.def file defines a_inpinfo. See IARRIVE_METHOD for information.

Toolkit ignores any changes made to the a_data_stored argument. If the current field is a multi-line text field, the a_data_stored argument is the first element in the array containing the storage data for each line of the field.

Changes made to a_data_displayed are reflected in the input field if %IDISPLAY_METHOD returns true. If the current field is a multi-line text field, the a_data_displayed argument is the first element in the array containing the display data for each line of the field. Note that the text returned in a_data_display is not limited by the display length or the view length.

If the calling routine is either I_DISPLAY, I_INPUT, or I_INPFLD (on Windows), the a_inprec argument contains the data area that was passed to that routine. (On UNIX and OpenVMS, this argument is not passed if I_INPFLD is the calling routine.)

Changes made to the a_attributes and a_color arguments are applied to the input field’s display if %IDISPLAY_METHOD returns true. These renditions will override those otherwise specified, specifically the default renditions (bold, 3), renditions set by U_REND and U_RSTREND, and field level renditions.

A_methoddata1 through a_methoddata20 are up to 20 additional optional arguments passed from I_INPUT, I_INPFLD, I_DISPLAY, or I_DSPFLD.

Any field with a user-defined data type will not invoke the %IDISPLAY_METHOD. Instead, the EDSPFLD_METHOD routine should be used to display directly into the field.

Toolkit will format a_data_display prior to calling %IDISPLAY_METHOD, but the data is not actually displayed until after the method returns.