This documentation supports the 18.05 version of Remedy Action Request System.

To view the latest version, select the version from the Product version menu.

ARCreateField

Note

You can continue to use C APIs to customize your application, but C APIs are not enhanced to support new capabilities provided by Java APIs and REST APIs.

Description

Creates a new field with the indicated name on the specified server. Forms can contain data and nondata fields. Nondata fields serve several purposes. Trim fields enhance the appearance and usability of the form (for example, lines, boxes, or static text). Control fields provide mechanisms for executing active links (for example, menus, buttons, or toolbar buttons). Other nondata fields organize data for viewing (for example, panels and panel holders) or show data from another form (for example, tables and columns).

An active link can be associated with only one control field (you can, however, select any combination of screen appearances for that field). A particular control field, however, can be associated with multiple active links. While information about nondata fields is stored on the server, they do not require storage space in the underlying database.

Privileges

BMC Remedy AR System administrator.

Synopsis

#include "ar.h"
#include "arerrno.h"
#include "arextern.h"
#include "arstruct.h"

int ARCreateField(
   ARControlStruct *control,
   ARNameType schema,
   ARInternalId *fieldId,
   ARBoolean reservedIdOK,
   ARNameType fieldName,
   ARFieldMappingStruct *fieldMap,
   unsigned int dataType,
   unsigned int option,
   unsigned int createMode,
   unsigned int fieldOption
   ARValueStruct *defaultVal,
   ARPermissionList *permissions,
   ARFieldLimitStruct *limit,
   ARDisplayInstanceList *dInstanceList,
   char *helpText,
   ARAccessNameType owner,
   char *changeDiary,
   ARPropList *objPropList,
   ARStatusList *status)

Input arguments

control

The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user and server fields are required.

If a valid overlay group is specified in the control record, the ARCreate* function creates a custom object that belongs to that group. If no group is specified, the function creates an origin object. To specify an overlay group, use the AR_SESS_CONTROL_PROP_DESIGN_OVERLAYGROUP variable of the ARSetSessionConfiguration function (see ARGetSessionConfiguration).

schema

The name of the form the field is linked to. The field must be associated with a single form that currently exists on the server.

fieldId

The internal ID of the field to create. The IDs of all fields and form views (VUIs) associated with a given form must be unique. Specify 0 for this parameter if you want the system to generate and return the ID. Otherwise, specify a value between 53686891 2 and 2147483647 (limited by AR_MAX_RESERVED_FIELD_ID in arstruct.h). If you specify a reserved ID, the system generates an error unless the reservedIdOK parameter is set to 1 (TRUE).

reservedIdOK

A flag that indicates whether you can create the field with a reserved ID. Specify 1 (TRUE) for this parameter to allow reserved IDs. Specify 0 (FALSE) if you want the system to generate an error when you specify a reserved ID for the fieldId parameter.

fieldName

The name of the field to create. The names of all fields and VUIs associated with a given form must be unique. The system uses this name when it creates the SQL view of the form for report writing purposes. The field name is used to identify a field in a workflow object more easily. The field name is different from the field label in that it is specific to a form, but not specific to a view of the form. See the dInstanceList parameter on dInstanceList for information about how to specify a field label.

fieldMap

A mapping to the underlying form in which to create the field. To create a field in a base form, specify a field type of 1 (AR_FIELD_REGULAR) in the structure. Otherwise, specify a field type of 2 (AR_FIELD_JOIN) and identify the member form (primary or secondary) and field ID for the new field. If the member form is also a join form, create field mappings in all nested join forms until you can map the field to an underlying base form. See Mapping fields in schemas.

dataType

The data type of the field to create.

2

AR_DATA_TYPE_INTEGER

Integer

3

AR_DATA_TYPE_REAL

Real

4

AR_DATA_TYPE_CHAR

Character

5

AR_DATA_TYPE_DIARY

Diary

6

AR_DATA_TYPE_ENUM

Selection

7

AR_DATA_TYPE_TIME

Date/time

10

AR_DATA_TYPE_DECIMAL

Fixed-point decimal. Values must be specified in C locale, for example 1234.56

11

AR_DATA_TYPE_ATTACH

Attachment

12

AR_DATA_TYPE_CURRENCY

Currency

31

AR_DATA_TYPE_TRIM

Trim

32

AR_DATA_TYPE_CONTROL

Control

33

AR_DATA_TYPE_TABLE

Table

34

AR_DATA_TYPE_COLUMN

Column

35

AR_DATA_TYPE_PAGE

Panel

36

AR_DATA_TYPE_PAGE_HOLDER

Panel holder

 

option

A flag that indicates whether users must enter a value in the field.

1:

Required (data fields only) (AR_FIELD_OPTION_REQUIRED).

2:

Optional (data fields only) (AR_FIELD_OPTION_OPTIONAL).

4:

Display-only (data fields only). Works like an optional field but doesn't write to the database (AR_FIELD_OPTION_DISPLAY).

 

createMode

A flag that indicates the permission status for the field when users submit entries. This parameter is ignored for display-only fields.

1:

Any user (including guest users) can enter data in the field when submitting (AR_FIELD_OPEN_AT_CREATE).

2:

Only users who have been granted permission can enter data in the field when submitting (AR_FIELD_PROTECTED_AT_CREATE).

 

fieldOption

A bitmask that indicates whether the field is to be audited or copied when other fields are audited.

Bit 0:

Audit this field. (AR_FIELD_BITOPTION_AUDIT)

Bit 1:

Copy this field when other fields in the form are audited. (AR_FIELD_BITOPTION_COPY)

Bit 2:

Indicates this field is for Log Key 1. (AR_FIELD_BITOPTION_LOG_KEY1)

Bit 3:

Indicates this field is for Log Key 2. (AR_FIELD_BITOPTION_LOG_KEY2)

Bits 2 and 3:

Indicates this field is for Log Key 3. ( AR_FIELD_BITOPTION_LOG_KEY3)

 

defaultVal

The value to apply if a user submits an entry with no field value (only applicable to data fields). The default value can be as many as 255 bytes in length (limited by AR_MAX_DEFAULT_SIZE) and must be of the same data type as the field. Specify NULL (or AR_DEFAULT_VALUE_NONE) for trim, control, panel, and panel holder fields or if you do not want to define a default value.

permissions

A list of zero or more groups who can access this field. Specify an empty permission list to define a field accessible only by users with administrator capability. Specify group ID 0 (Public) to provide access to all users. The permission value that you assign for each group determines whether users in that group can modify the field. See Field permission values for.

limit

The value limits for the field and other properties specific to the field's type. See Defining field limits for a description of the contained structure that applies to the type of field that you are creating. The limits and properties that you define must be of the same data type as the field. Specify NULL (or AR_FIELD_LIMIT_NONE) for trim and control fields or if you do not want to define any limits or properties.

dInstanceList

A list of zero or more display properties to associate with the field. You can define both display properties common to all form views (VUIs) and display properties specific to particular form views. The system includes the field in each view that you specify, regardless of whether you define any display properties for those views. If you do not specify a property for a particular view, the system uses the default value (if defined). Specify NULL for this parameter if you do not want to define any display properties.

helpText

The help text associated with the field. This text can be of any length. Specify NULL for this parameter if you do not want to associate help text with this object.

owner

The owner for the field. The owner defaults to the user performing the operation if you specify NULL for this parameter.

changeDiary

The initial change diary associated with the field. This text can be of any length. The server adds the user making the change and a time stamp when it saves the change diary. Specify NULL for this parameter if you do not want to associate change diary text with this object.

objPropList

A list of server object properties. If this parameter is set to NULL, a list with zero properties is associated with the object, and zero properties are returned when an ARGetField is performed. See Server object properties and structures.

Return values

status

A list of zero or more notes, warnings, or errors generated from a call to this function. For a description of all possible values, see Error checking.

Display properties

You can specify the following display properties in any order. Avoid specifying a property more than once, because the system then selects one of your definitions at random.

Note

When using the driver program to call the functions in your API program, you need to specify the property number instead of the property name. The property number is listed for each display property name in the ar.h file in the api/include directory. See Using the driver program for more information.

  • AR_DPROP_ALIGN (unsigned long): A value that indicates the vertical alignment of text within its bounding box.

    1:

    Top-aligned (AR_DVAL_ALIGN_TOP).

    2:

    Centered (AR_DVAL_ALIGN_MIDDLE) (default setting).

    4:

    Bottom-aligned (AR_DVAL_ALIGN_BOTTOM).

  • AR_DPROP_ATTACH_COLGRAD_COLOR (character string): When AR_DPROP_ATTACH_COLGRAD_TYPE is set to a gradient type, this value specifies the main color in the effect.
  • AR_DPROP_ATTACH_COLGRADBKG_COLOR (character string): When AR_DPROP_ATTACH_COLGRAD_TYPE is set to a gradient type, this value specifies the second color in the effect.
  • AR_DPROP_ATTACH_COLGRAD_TYPE (unsigned long): A value that enables a color fill gradient effect for a background color of the attachment pool column header.
  • AR_DPROP_ATTACH_COLHDRTXT_COLOR (character string): The color of the text of the attachment pool column header.
  • AR_DPROP_ATTACH_FTRGRAD_COLOR (character string): When AR_DPROP_ATTACH_FTRGRAD_TYPE is set to a gradient type, this value specifies the main color in the effect.
  • AR_DPROP_ATTACH_FTRGRADBKG_COLOR (character string): When AR_DPROP_ATTACH_FTRGRAD_TYPE is set to a gradient type, this value specifies the second color in the effect.
  • AR_DPROP_ATTACH_FTRGRAD_TYPE (unsigned long): A value that enables a color fill gradient effect for a background color of the attachment pool footer.
  • AR_DPROP_AUTO_REFRESH (unsigned long): A value that indicates whether automatic refresh is enabled (only applicable to table fields). Specify 0 to disable (AR_DVAL_AUTO_REFRESH_NONE) and 1 to enable (AR_DVAL_AUTO_REFRESH_TABLE_MAX). When automatic refresh is enabled, the contents of the table field are updated when the entry is displayed in a Modify window. When automatic refresh is disabled, the table appears empty until the user clicks within its borders to refresh it.
  • AR_DPROP_BACKGROUND_MODE (unsigned long): A value that indicates whether the background of a field is opaque or transparent (only applicable to trim fields). Specify 0 for opaque (AR_DVAL_BKG_MODE_OPAQUE) or 1 for transparent (AR_DVAL_BKG_MODE_TRANSPARENT). The default value is 0 (opaque).
  • AR_DPROP_BBOX (ARCoordList): A set of coordinates (X,Y) that specify the screen boundaries (bounding box) for the field (applicable to all fields except panel and column fields). The first coordinate pair identifies the upper-left corner for the field. The second coordinate pair identifies the lower-right corner (see AR_DPROP_COORDS).
  • AR_DPROP_BUTTON_2D (unsigned long): A flag that indicates whether the button appears as a two-dimensional image with no border (only applicable to control fields). Valid values for this property are 1 (TRUE) and 0 (FALSE). The default value is 0 (three-dimensional with borders).
  • AR_DPROP_BUTTON_IMAGE_POSITION (unsigned long): A value that determines the position of the button image relative to the button label (only applicable to control fields). The default value is 0 (centered, no label).

    0:

    AR_DVAL_IMAGE_CENTER (centered, no label).

    1:

    AR_DVAL_IMAGE_LEFT (to the left of the label).

    2:

    AR_DVAL_IMAGE_RIGHT (to the right of the label).

    3:

    AR_DVAL_IMAGE_ABOVE (above the label).

    4:

    AR_DVAL_IMAGE_BELOW (below the label).

  • AR_DPROP_BUTTON_MAINTAIN_RATIO (unsigned long): A flag that indicates whether a scaled button image preserves its original width-to-height ratio (only applicable to control fields). Valid values for this property are 1 (TRUE) and 0 (FALSE). The default value is 0 (do not preserve ratio). This property only affects the image when AR_DPROP_BUTTON_SCALE_IMAGE is TRUE.
  • AR_DPROP_BUTTON_SCALE_IMAGE (unsigned long): A flag that indicates whether the button image shrinks or grows to fill the space available after allocating space for the button label (only applicable to control fields). Valid values for this property are 1 (TRUE) and 0 (FALSE). The default value is 0 (leave image at original size).
  • AR_DPROP_BUTTON_TEXT (character string): The button label for the field (only applicable to control fields). This label can be as many as 30 bytes in length (limited by AR_MAX_NAME_SIZE).
  • AR_DPROP_CHARFIELD_AUTO_COMPLETE (unsigned long): A value that controls whether Auto Completion is in effect for a character field that has a menu attached. The default value is None.

    0:

    None (AR_DVAL_AUTO_COMPLETE_NONE).

    1:

    Leading match (AR_DVAL_AUTO_COMPLETE_LEADING).

    2:

    Anywhere Match (AR_DVAL_AUTO_COMPLETE_ANYWHERE).

  • AR_DPROP_CHARFIELD_AUTO_COMPLETE_MATCH_BY (unsigned long): A value that determines how Auto Completion matching occurs.

    0:

    Match by menu value (AR_DVAL_AUTO_COMPLETE_MATCH_BY_VALUE).

    1:

    Match by menu label (AR_DVAL_AUTO_COMPLETE_MATCH_BY_LABEL).

  • AR_DPROP_CHARFIELD_DISPLAY_TYPE (unsigned long): A value that indicates whether the character field is a drop-down list, editable field, edit/masked field, or file system browser.

    0:

    Editable field (AR_DVAL_CHARFIELD_EDIT)

    1:

    Drop-down field (AR_DVAL_CHARFIELD_DROPDOWN)

    2:

    Edit Masked (AR_DVAL_CHARFIELD_MASKED)

    3:

    File system browser (AR_DVAL_CHARFIELD_FILE)

    4:

    Rich text field (AR_DVAL_CHARFIELD_RICH_TEXT)

    5:

    Editable rich text field (AR_DVAL_CHARFIELD_RICH_TEXT_ADV)

  • AR_DPROP_CNTL_TYPE (unsigned long): A bitmask that indicates the screen appearance for a control field.

    Bit 0:

    Button ( AR_DVAL_CNTL_BUTTON ).

    Bit 1:

    Menu item ( AR_DVAL_CNTL_MENU ).

    Bit 2:

    Toolbar button ( AR_DVAL_CNTL_TOOLBAR ).

  • AR_DPROP_COL_HEADBKG_GRADTYPE (unsigned long): A value that enables a color fill gradient effect for a background color of the table column header.
  • AR_DPROP_COL_HEADBKG_GRADCOLOR (character string): When AR_DPROP_COL_HEADBKG_GRADTYPE is set to a gradient type, this value specifies the main color in the effect.
  • AR_DPROP_COL_HEADBKG_GRADBKGCOLOR (character string): When AR_DPROP_COL_HEADBKG_GRADTYPE is set to a gradient type, this value specifies the second color in the effect.
  • AR_DPROP_COLOR_FILL_GRADIENT (character string): When AR_DPROP_COLOR_FILL_GRADIENT_EFFECT is set to some gradient effect, this value specifies the second color in the effect. See other color properties for value examples.
  • AR_DPROP_COLOR_FILL_GRADIENT_EFFECT (unsigned long): A value that enables a color fill gradient effect for a background color of panel field. All the choices except No gradient require specification of AR_DPROP_COLOR_FILL_GRADIENT.

    0:

    No gradient (AR_DVAL_GRADIENT_EFFECT_NONE).

    1:

    Horizontal and linear (AR_DVAL_GRADIENT_EFFECT_LINEAR_HORIZONTAL).

    2:

    Vertical and linear (AR_DVAL_GRADIENT_EFFECT_LINEAR_VERTICAL).

    3:

    Horizontal and reflected (AR_DVAL_GRADIENT_EFFECT_REFLECTED_HORIZONTAL).

    4:

    Vertical and reflected (AR_DVAL_GRADIENT_EFFECT_REFLECTED_VERTICAL).

  • AR_DPROP_COLOR_FILL_OPACITY (real): A value that controls the opacity of the background color of a panel. Specify a real number between 0 (completely transparent) and 1.0 (completely opaque). The default is 1.0.
  • AR_DPROP_COLOR_GRADIENT_HEADER (character string): When AR_DPROP_COLOR_FILL_GRADIENT_EFFECT_HEADER is set to some gradient effect, this value specifies the second color in the effect. See other color properties for value examples.
  • AR_DPROP_COLOR_GRADIENT_EFFECT_HEADER (unsigned long): The gradient effect, if any, for headers of panels in a collapsible or accordion panel holder. For appropriate values, see AR_DPROP_COLOR_FILL_GRADIENT_EFFECT.
  • AR_DPROP_COLUMN_ORDER (integer): The order of a column in a table field. The column with the lowest value is the left-most displayed.
  • AR_DPROP_COLUMN_WIDTH (integer): The width of a column in a table field.
  • AR_DPROP_COORDS (ARCoordList): A set of coordinates (X,Y) that specify the vertex location (only applicable to line- and box-type trim fields). For line-type trim fields, identify the vertices of the line segment by using two coordinate pairs. For box-type trim fields, identify the corners of the box (clockwise from the upper-left corner) by using four coordinate pairs (see also AR_DPROP_BBOX).
    To minimize display differences across a variety of operating systems and screen resolutions, the clients standardize all coordinate values before storing them in the database and then map these values to the current environment on retrieval. When specifying (or retrieving) coordinate data for any property with ARCoordList, you must apply the same translation algorithms in order for BMC Remedy Developer Studio to display the field correctly. For additional information, see Using ARCoordList to specify field size and location.
  • AR_DPROP_DATA_BBOX (ARCoordList): A set of coordinates (X,Y) that specify the screen boundaries (bounding box) for the field's data area (only applicable to data fields). For example, this property locates the entry box for a character field and the buttons for a radio button selection field. The first coordinate pair identifies the upper-left corner for the data area. The second coordinate pair identifies the lower-right corner. The coordinates specified are relative to the field's location as specified in its AR_DPROP_BBOX property, not to the window or panel containing it.
  • AR_DPROP_DATA_COLS (unsigned long): The number of text columns to display for the field (only applicable to data fields). AR_DPROP_DATA_BBOX overrides this value.
  • AR_DPROP_DATA_EXPAND_BBOX (ARCoordList): A set of coordinates (X,Y) that specify the screen boundaries (bounding box) for the field's text editor button (only applicable to diary and long character fields). The first coordinate pair identifies the upper-left corner for the button. The second coordinate pair identifies the lower-right corner. The coordinates specified are relative to the field's location as specified in its AR_DPROP_BBOX property, not to the window.
  • AR_DPROP_DATA_MENU (unsigned long): A flag that indicates whether the field has a drop-down list (only applicable to selection fields). Valid values for this property are 1 (TRUE) and 0 (FALSE). The default value is 0 (no drop-down list).
  • AR_DPROP_DATA_MENU_BBOX (ARCoordList): A set of coordinates (X,Y) that specify the screen boundaries (bounding box) for the field's menu button (only applicable to character fields with an attached menu). The first coordinate pair identifies the upper-left corner for the button. The second coordinate pair identifies the lower-right corner. The coordinates specified are relative to the field's location as specified in its AR_DPROP_BBOX property, not to the window.
  • AR_DPROP_DATA_RADIO (unsigned long): A flag that indicates whether the field uses radio option buttons (only applicable to selection fields). Valid values for this property are 1 (TRUE) and 0 (FALSE). The default value is 0 (does not use option buttons).
  • AR_DPROP_DATA_ROWS (unsigned long): The number of text rows to display for the field (only applicable to data fields).
  • AR_DPROP_DATA_SPIN (unsigned long): A flag that indicates whether the field has a numeric spinner (only applicable to integer fields). Valid values for this property are T (TRUE) and F (FALSE). The default value is F (no numeric spinner).
  • AR_DPROP_DATETIME_POPUP (unsigned long): A value that indicates the display type of a date/time field. The default value is 0 (both date and time).

    0:

    Both date and time (AR_DVAL_DATETIME_BOTH) (default setting).

    1:

    Time only (AR_DVAL_DATETIME_TIME).

    2:

    Date only (AR_DVAL_DATETIME_DATE).

  • AR_DPROP_DEPTH_EFFECT (unsigned long):A value that indicates the three-dimensional style for the field. This property, in conjunction with the AR_DPROP_LINE_WIDTH property, determines the overall look of line- and box-type trim fields.

    0:

    No three-dimensional effect (AR_DVAL_DEPTH_EFFECT_FLAT).

    1:

    Field appears to lie above screen surface (AR_DVAL_DEPTH_EFFECT_RAISED).

    2:

    Field appears to lie below screen surface (AR_DVAL_DEPTH_EFFECT_SUNKEN).

    4:

    Field appears to be etched into screen surface (AR_DVAL_DEPTH_EFFECT_ETCHED).

  • AR_DPROP_DISPLAY_PARENT (unsigned long): A value that indicates the parent field that the field appears in. Specify the field ID of the parent. A panel holder field is the parent of the panel fields displayed in it, and a panel field is the parent of the fields displayed in it. A value of 0 indicates that the field's parent is the form view and not another field. The default value is 0.
  • AR_DPROP_DRILL_DOWN (unsigned long): A bitmask that indicates whether drill-down is enabled for a table field. Specify bit 0 to disable and 1 to enable. When drill-down is enabled and a user double-clicks a row in the table field, a Modify window opens for the entry represented by that row.
  • AR_DPROP_DROP_SHADOW (unsigned long): A value that indicates a drop shadow for panels and panel holders.

    0:

    No shadow (AR_DVAL_DROP_SHADOW_NONE) (default setting).

    1:

    Drop shadow below and to the right of the object border (AR_DVAL_DROP_SHADOW_NORTH_WEST).

  • AR_DPROP_ENABLE (unsigned long): A value that specifies the enabled or disabled status of the field. For control fields, this setting applies to all specified screen appearances (see AR_DPROP_CNTL_TYPE).

    1:

    View and select only (data); disabled (trim or control) (AR_DVAL_ENABLE_READ_ONLY).

    2:

    View, select, and change (data); enabled (trim or control) (AR_DVAL_ENABLE_READ_WRITE) (default setting).

    3:

    Disabled (data, trim, or control) (AR_DVAL_ENABLE_DISABLE).

  • AR_DPROP_ENABLE_CLEAR (unsigned long): A value that determines whether the special value "(Clear)" is added to character fields of type drop-down list. Specify AR_DVAL_ENABLE_CLEAR_ALWAYS to add the special value in all form display modes. Specify AR_DVAL_ENABLE_CLEAR_SEARCH_ONLY to remove the special value in new or modify modes, forcing users to enter a value.
  • AR_DPROP_FIELD_CUSTOMSTYLE (character string): Specifies a custom CSS style for a field.
  • AR_DPROP_FIELD_HIGHLIGHT (unsigned long): A flag that enables field highlighting for a field to occur when active links change the value of the field. Specify AR_DVAL_FIELD_HIGHLIGHT_DISABLE (the default) or AR_DVAL_FIELD_HIGHLIGHT_ENABLE.
  • AR_DPROP_FIELD_HIGHLIGHT_END_COLOR (character string): A color value that specifies the second background color as part of the field highlighting effect, enabled by setting the AR_DPROP_FIELD_HIGHLIGHT property. See other color properties for value examples. The default is white.
  • AR_DPROP_FIELD_HIGHLIGHT_START_COLOR (character string): A color value that specifies the first background color as part of the field highlighting effect, enabled by setting the AR_DPROP_FIELD_HIGHLIGHT property. See other color properties for value examples. The default is white.
  • AR_DPROP_FIELD_MAX_HEIGHT (integer): When a field is positioned within a container using fill layout, this value specifies the maximum width of the field.
  • AR_DPROP_FIELD_MAX_WIDTH (integer): When a field is positioned within a container using fill layout, this value specifies the maximum width of the field.
  • AR_DPROP_FIELD_MIN_HEIGHT (integer): When a field is positioned within a container using fill layout, this value specifies the minimum height of the field. If the container shrinks below this value, a scroll bar will appear.
  • AR_DPROP_FIELD_MIN_WIDTH (integer): When a field is positioned within a container using fill layout, this value specifies the minimum width of the field. If the container shrinks below this value, a scroll bar will appear.
  • AR_DPROP_FIELD_ROUNDED (character string): This value specifies rounding of corners for panel fields using the web. To specify all corners rounded to the same radius, give a single radius value such as 10. To specify each corner's radius independently, use a comma-separated list (such as 5, 10, 5, 10) where the values are applied to the top-left, top-right, bottom-left, and bottom-right corners, respectively. By default, all corners are square.
  • AR_DPROP_HIDE_PANELHOLDER_BORDERS: This value is a flag to specify that a panel holder should be borderless. Specify FALSE (0) for the default border, or TRUE (1) to suppress the border.
  • AR_DPROP_HTML_TEXT (character string): The text for a text-type trim field that includes a URL. The string must include a standard HTML anchor tag (<A> ) that encloses the text to be linked and specifies the URL to link to. Text that does not fit within its bounding box causes the form window to scale up to accommodate it (see AR_DPROP_BBOX).
  • AR_DPROP_HTML_TEXT_COLOR (character string): The color of the linked text for a text-type trim field that includes a URL (see AR_DPROP_HTML_TEXT). Use one of the values listed for AR_DPROP_LABEL_COLOR_TEXT or specify a custom color as 0xBBGGRR, a string concatenating the two-digit hexadecimal values for blue, green, and red. The default value is the link color specified in the user's browser preferences.
  • AR_DPROP_IMAGE (ARByteList): The icon image for a toolbar-type control field. Specify a byte list type of 1 (AR_BYTE_LIST_WIN30_BITMAP) for images in bitmap (.bmp) and DIB (.dib) format. Specify 0 (AR_BYTE_LIST_SELF_DEFINED) for all other image formats.

    Note

    The only image formats currently supported on toolbar control fields are bitmap and DIB. The only image size currently supported is 16 pixels wide by 15 pixels high. Images of other sizes are not scaled to fit. When creating images, use simple images and the 216-color palette for best results.

  • AR_DPROP_JUSTIFY (unsigned long): A value that indicates the horizontal justification of text within its bounding box.

    1:

    Left-aligned (AR_DVAL_JUSTIFY_LEFT).

    2:

    Centered (AR_DVAL_JUSTIFY_CENTER).

    4:

    Right-aligned (AR_DVAL_JUSTIFY_RIGHT).

  • AR_DPROP_LABEL (character string): The screen label for the field (only applicable to data fields). This label can be as many as 30 bytes in length (limited by AR_MAX_NAME_SIZE).
  • AR_DPROP_LABEL_BBOX (ARCoordList): A set of coordinates (X,Y) that specify the screen boundaries (bounding box) for the field label (only applicable to data fields). The first coordinate pair identifies the upper-left corner for the label. The second coordinate pair identifies the lower-right corner. The coordinates specified are relative to the field's location as specified in its AR_DPROP_BBOX property, not to the window or panel containing it.
  • AR_DPROP_LABEL_COLOR_TEXT (character string): The color of the field label. Specify the color as #BBGGRR, a string concatenating the two-digit hexadecimal values for blue, green, and red.
  • AR_DPROP_LABEL_POS_ALIGN (unsigned long): A value that indicates the vertical alignment of the label within the sector (see the Note that follows).

    1:

    Top-aligned (AR_DVAL_ALIGN_TOP).

    2:

    Middle-aligned (AR_DVAL_ALIGN_MIDDLE).

    4:

    Bottom-aligned (AR_DVAL_ALIGN_BOTTOM).

    Note

    The following two combinations of values for the AR_DPROP_LABEL_POS_SECTOR, AR_DPROP_LABEL_POS_JUSTIFY, and AR_DPROP_LABEL_POS_ALIGN properties provide the best-looking form views in BMC Remedy Mid Tier:

    SECTOR

    JUSTIFY

    ALIGN

    Label position

    north

    left

    bottom

    >

    top

    west

    left

    top

    >

    left

  • AR_DPROP_LABEL_POS_JUSTIFY (unsigned long): A value that indicates the horizontal alignment of the label within the sector (see the Note that follows AR_DPROP_LABEL_POS_ALIGN).

    1:

    Left-justified (AR_DVAL_JUSTIFY_LEFT).

    2:

    Center-justified (AR_DVAL_JUSTIFY_CENTER).

    4:

    Right-justified (AR_DVAL_JUSTIFY_RIGHT).

  • AR_DPROP_LABEL_POS_SECTOR (bitmask): A value that indicates the label position relative to the field. This property, in conjunction with the AR_DPROP_LABEL_POS_JUSTIFY and AR_DPROP_LABEL_POS_ALIGN properties, determines the specific placement and alignment of the screen label (see the Note that follows AR_DPROP_LABEL_POS_ALIGN).

    0:

    Suppress label display (AR_DVAL_SECTOR_NONE).

    2:

    Above the field (AR_DVAL_SECTOR_NORTH).

    16:

    Left of the field (AR_DVAL_SECTOR_WEST) (default setting).

  • AR_DPROP_LAYOUT_POLICY (unsigned long): This value is used for views and fields that act like containers (panel fields) to determine how the container will arrange the layout of its child fields. Specify AR_DVAL_LAYOUT_XY if the container should honor the field's bounding box (this is the default). Specify AR_DVAL_LAYOUT_FILL to have the container automatically resize all visible children to the width of the container, resize the height of all children to be equal to the container's total height, and stack the visible children vertically on top of each other. Specify AR_DVAL_LAYOUT_FLOW for RTF fields to have the container automatically resize all visible children to the width of the container, resize the height of all children to be equal to the container's total height, and stack the visible children on top of each other.
  • AR_DPROP_LINE_WIDTH (unsigned long): The line width for the field (only applicable to line- and box-type trim fields). The default value is 3 pixels.
  • AR_DPROP_LOCALIZATION_REQUIRED (unsigned long): A value used to mark a field for some special purpose, with values TRUE (1) or FALSE (0). The default is FALSE. This flag was introduced to allow developers to keep track of fields that require localization. It has no effect at runtime.
  • AR_DPROP_MENU_HELP (character string): The help text for a menu-type control field. This text can be as many as 30 bytes in length (limited by AR_MAX_NAME_SIZE).
  • AR_DPROP_MENU_MODE (unsigned long): A value that indicates the type of menu item (only applicable to control fields).

    0:

    Leaf-level menu item (AR_DVAL_CNTL_ITEM).

    2:

    Separator item (AR_DVAL_CNTL_SEPARATOR).

    5:

    Top- or intermediate-level menu item (AR_DVAL_CNTL_A_MENU).

  • AR_DPROP_MENU_PARENT (unsigned long): A value that specifies the parent menu item for the field (only applicable to control fields). Specify the field ID of the parent control field for leaf- or intermediate-level menu items. Specify 0 for top-level menu items.
  • AR_DPROP_MENU_POS (unsigned long): A value that determines the menu position for the field (only applicable to control fields). For leaf- or intermediate-level menu items, the value associated with each field in a form view (VUI) determines the top-to-bottom order of the items in the menu (from lowest to highest, starting with one). For top-level menu items, this value determines the left-to-right order of the items in the menu bar.
  • AR_DPROP_MENU_TEXT (character string): The menu item text for the field (only applicable to control fields). This text can be as many as 30 bytes in length (limited by AR_MAX_NAME_SIZE).
  • AR_DPROP_NAVBAR_INITIAL_SELECTED_ITEM (field ID): Specifies that when you open a form, the navigation bar is initialized with the selected item.
  • AR_DPROP_NAVBAR_WORKFLOW_ON_SELECTED_ITEM (integer): Specifies whether workflow is executed when the item is selected. Values are 1 (TRUE, execute workflow on selection) or 0 (FALSE, select the item but do not execute workflow).
  • AR_DPROP_NAVBAR_SELECT_ITEM_ON_CLICK (integer): Specifies whether to move selection to an item when that item is clicked. Values are 1 (TRUE, move selection on click) or 0 (FALSE, do nothing on click).
  • AR_DPROP_NONE: Indicates the NULL display property. You can specify no display properties by passing an empty property list. This property is ignored if the list also contains other display properties.
  • AR_DPROP_ORIENTATION (unsigned long): A value that specifies whether child fields are arranged next to each other horizontally (AR_DVAL_ORIENTATION_HORIZONTAL) or vertically at 90 0 (AR_DVAL_ORIENTATION_VERTICAL) or vertically at 270 0 (AR_DVAL_ORIENTATION_VERTICAL_UP). The default is horizontal.
  • AR_DPROP_PAGE_BODY_STATE (unsigned long): This value controls whether a panel within a collapsible or accordion panel holder is initially collapsed (specify AR_DVAL_PAGE_BODY_COLLAPSE) or expanded (specify AR_DVAL_PAGE_BODY_EXPAND). The default is AR_DVAL_PAGE_BODY_COLLAPSE.
  • AR_DPROP_PAGE_HEADER_COLOR (character string): The background color of a header used in a panel within a collapsible, accordion, or splitter panel holder. See other color properties for value examples.
  • AR_DPROP_PAGE_HEADER_STATE (unsigned long): A flag to indicate whether a header is displayed as part of a panel within a collapsible panel holder, using values AR_DVAL_PAGE_HEADER_HIDDEN or AR_DVAL_PAGE_HEADER_VISIBLE. The default is AR_DVAL_PAGE_HEADER_HIDDEN.
  • AR_DPROP_PAGE_INITIAL_SIZE (integer): This value applies to a panel field that is contained by a collapsible or splitter panel holder. It controls the initial size in the dimension appropriate to the orientation--for example, in a vertical panel holder it controls the height.
  • AR_DPROP_PAGE_MAX_SIZE (integer): This value applies to a panel field that is contained by a splitter panel holder. It controls the maximum size in the dimension appropriate to the orientation--for example, in a vertical panel holder it controls the maximum height. Note that as the container resizes, the penultimate panel might grow beyond this value.
  • AR_DPROP_PAGE_MIN_SIZE (integer): This value applies to a panel field that is contained by a splitter panel holder. It controls the minimum size in the dimension appropriate to the orientation--for example, in a vertical panel holder it controls the minimum height.
  • AR_DPROP_PAGEHOLDER_DISPLAY_TYPE (unsigned long): This value controls the style of a panel holder. The default is Tabbed.

    0:

    Tabbed (AR_DVAL_PAGEHOLDER_DISPLAY_TYPE_TABCTRL)

    1:

    Collapsible (AR_DVAL_PAGEHOLDER_DISPLAY_TYPE_STACKEDVIEW)

    2:

    Splitter (AR_DVAL_PAGEHOLDER_DISPLAY_TYPE_SPLITTERVIEW)

    3:

    Accordion (AR_DVAL_PAGEHOLDER_DISPLAY_TYPE_ACCORDION)

  • AR_DPROP_PAGEHOLDER_INIT_PAGE (integer): Specifies relative offset of the panel to initially display in a panel holder. The default is 0.
  • AR_DPROP_PAGEHOLDER_MARGIN_BOTTOM (integer): Specifies the bottom internal margin for panel holder. The default is 0.
  • AR_DPROP_PAGEHOLDER_MARGIN_LEFT (integer): Specifies the left internal margin for panel holder. The default is 0.
  • AR_DPROP_PAGEHOLDER_MARGIN_RIGHT (integer): Specifies the right internal margin for panel holder. The default is 0.
  • AR_DPROP_PAGEHOLDER_MARGIN_TOP (integer): Specifies the top internal margin for panel holder. The default is 0.
  • AR_DPROP_PAGEHOLDER_SPACING (integer): Specifies the internal vertical spacing between panels within a panel holder. The default is 0.
  • AR_DPROP_PANELHOLDER_SPLITTER (unsigned long): A value that applies to the splitter state property of the panel holder field. It controls whether the splitter bar is visible and can be dragged to resize the panels. The splitter bar can be manipulated by the end user. The default value is AR_DVAL_SPLITTER_SHOW.

    0:

    Splitter bar is not visible and cannot be dragged (AR_DVAL_SPLITTER_HIDE).

    1:

    Splitter bar is visible and can be dragged (AR_DVAL_SPLITTER_SHOW).

    2:

    Splitter bar is not visible but can be dragged (AR_DVAL_SPLITTER_INVISIBLE).

  • AR_DPROP_PUSH_BUTTON_IMAGE (ARByteList): The icon image for a button. Specify a byte list type of 1 (AR_BYTE_LIST_WIN30_BITMAP) for images in bitmap (.bmp) and DIB (.dib) format. Specify 2 (AR_BYTE_LIST_JPEG) for JPEG (.jpg or .jpeg) format.

    Note

    The only image formats currently supported on button fields are JPEG, bitmap, and DIB. There is no limit to the pixel dimensions or file size of a button image, but large images can slow down your system's performance. When creating images, use simple images and the 216-color web palette for best results.

  • AR_DPROP_SORT_DIR (integer): A value that indicates the sort direction of a column in a table field. Specify 0 for ascending (AR_DVAL_SORT_DIR_ASCENDING) and 1 for descending (AR_DVAL_SORT_DIR_DESCENDING).
  • AR_DPROP_SORT_SEQ (integer): The sort order of a column in a table field. The system sorts based on the column with the lowest value first. To keep from sorting based on a column, specify 0 (the default).
  • AR_DPROP_TAB_ORDER (unsigned long): A value that determines the field tab order (from lowest to highest).
  • AR_DPROP_TABLE_COL_DISPLAY_TYPE (unsigned long): Specifies the display type of a column field.

    0:

    Non-editable (AR_DVAL_TABLE_COL_DISPLAY_NONEDITABLE)

    1:

    Allow editing (AR_DVAL_TABLE_COL_DISPLAY_EDITABLE)

    2:

    Display HTML (AR_DVAL_TABLE_COL_DISPLAY_HTML)

    3:

    Display as a cell field in a cell-based table (AR_DVAL_TABLE_COL_DISPLAY_PAGE_DATA)

  • AR_DPROP_TABLE_COLUMN_CHECKBOX (unsigned long): A value that determines whether a select/cancel all check-box column is added to a list view or results list table in a browser. If the column is added to the table, the Select All and Deselect All buttons do not appear in the table footer. For more information, see, Adding a Select All or Cancel All check-box column to tables.

    0:

    (Default) Do not add a select/cancel all check-box column to the table (AR_DVAL_TABLE_COLUMN_CHECKBOX_DISABLE).

    1:

    Add a select/cancel all check-box column to the table (AR_DVAL_TABLE_COLUMN_CHECKBOX_ENABLE).

  • AR_DPROP_TABLE_COLUMN_HEADER_TEXT_COLOR (character string): The color of the text in the column header used in a table.
  • AR_DPROP_TABLE_DISPLAY_TYPE (integer): Dictates the appearance of a table field in a browser.

    0:

    Standard table (AR_DVAL_TABLE_DISPLAY_TABLE).

    1:

    Results list table (AR_DVAL_TABLE_DISPLAY_RESULTS_LIST).

    2:

    Notification alert table (AR_DVAL_TABLE_DISPLAY_NOTIFICATION).

    3:

    Display from a single source table (AR_DVAL_TABLE_DISPLAY_SINGLE_TABLE_TREE).

    4:

    (reserved for future use)

    5:

    Display as a cell-based table (AR_DVAL_TABLE_DISPLAY_PAGE_ARRAY)

  • AR_DPROP_TABLE_HDRFTR_GRADTYPE (unsigned long): A value that enables a color fill gradient effect for a background color of the table header and footer.
  • AR_DPROP_TABLE_HDRFTR_GRADCOLOR (character string): When AR_DPROP_TABLE_HDRFTR_GRADTYPE is set to a gradient type, this value specifies the main color in the effect.
  • AR_DPROP_TABLE_HDRFTR_GRADBKGCOLOR (character string): When AR_DPROP_TABLE_HDRFTR_GRADTYPE is set to a gradient type, this value specifies the second color in the effect.
  • AR_DPROP_TABLE_PAGE_ARRAY_BOTTOM_MARGIN (integer): Specifies the bottom internal margin for a cell-based table. The default is 0.
  • AR_DPROP_TABLE_PAGE_ARRAY_HOR_SPACE (integer): For a cell-based table, specifies how much spacing should appear between horizontally adjacent repeating panels. The default is 0.
  • AR_DPROP_TABLE_PAGE_ARRAY_LEFT_MARGIN (integer): Specifies the left internal margin for a cell-based table. The default is 0.
  • AR_DPROP_TABLE_PAGE_ARRAY_RIGHT_MARGIN (integer): Specifies the right internal margin for a cell-based table. The default is 0.
  • AR_DPROP_TABLE_PAGE_ARRAY_TOP_MARGIN (integer): Specifies the top internal margin for a cell-based table. The default is 0.
  • AR_DPROP_TABLE_PAGE_ARRAY_VER_SPACE (integer): For a cell-based table, specifies how much spacing should appear between horizontally adjacent repeating panels. The default is 0.
  • AR_DPROP_TABLE_PAGE_VISIBLE_COLUMNS (integer): Specify the number of visible columns to display for a cell-based table. The default is 1. Note that when a cell-based table is in a fill layout, the number of columns is dynamically determined based on the width of the containing field.
  • AR_DPROP_TABLE_PANEL_BBOX (ARCoordList): This value is used when rendering cell-based tables to determine the dimensions of the repeating area.
  • AR_DPROP_TEXT (character string): The text for a text-type trim field. Text that does not fit within its bounding box causes the form window to scale up to accommodate it (see AR_DPROP_BBOX).
  • AR_DPROP_TEXT_FONT_STYLE (character string): The name of the font style to use for a text-type trim field.

    Editor:

    Font used for data fields.

    Optional:

    Font used for optional data field labels.

    PushButton:

    Font used for button labels.

    System:

    Font used for system-generated data field labels.

    RadioButton:

    Font used for option button choices.

    Required:

    Font used for required data field labels.

    Header1:

    Font used for titles.

    Header2:

    Font used for major headings.

    Header3:

    Font used for minor headings.

    Note:

    Font used for notes.

    Detail:

    Font used for detail information.

  • AR_DPROP_TOOLBAR_MODE (unsigned long): A value that indicates the type of toolbar item (only applicable to control fields).

    0:

    Toolbar button (AR_DVAL_CNTL_ITEM).

    2:

    Toolbar separator (AR_DVAL_CNTL_SEPARATOR).

  • AR_DPROP_TOOLBAR_POS (unsigned long): A value that determines the toolbar position for the field (only applicable to control fields). The value associated with each field in a form view (VUI) determines the left-to-right order of the icons in the toolbar (from lowest to highest, starting with one).
  • AR_DPROP_TOOLTIP (character string): The tooltip text for a toolbar-type control field. This text can be as many as 30 bytes in length (limited by AR_MAX_NAME_SIZE).
  • AR_DPROP_TRIM_TYPE (unsigned long): A value that indicates the type of trim field.

    1:

    Horizontal or vertical line (AR_DVAL_TRIM_LINE).

    2:

    Box (rectangle) (AR_DVAL_TRIM_SHAPE).

    3:

    One or more rows of text (AR_DVAL_TRIM_TEXT).

  • AR_DPROP_VERTNAV_SUBLEVELTWO_COLOR (character string): The sub level alternate background color. This setting is applicable only to Vertical Navigation Bar in the Flyout mode.
  • AR_DPROP_VIEW_BORDER_COLOR (character string): The color of the border of the view fields.
  • AR_DPROP_VIEWFIELD_BORDERS: A value that indicates whether borders are hidden or shown for view fields.

    0:

    For BMC Remedy Mid Tier, the borders are shown based on the display (AR_DVAL_VIEWFIELD_BORDERS_DEFAULT).

    1:

    No borders on view fields (AR_DVAL_VIEWFIELD_BORDERS_NONE).

    2:

    Borders on view fields (AR_DVAL_VIEWFIELD_BORDERS_ENABLE).

  • AR_DPROP_VIEWFIELD_SCROLLBARS: A value that indicates whether scroll bars are hidden or shown for view fields.

    0:

    Add scroll bars if needed. (AR_DVAL_VIEWFIELD_SCROLLBARS_AUTO).

    1:

    Always show scroll bars (AR_DVAL_VIEWFIELD_SCROLLBARS_ON).

    2:

    Hide scroll bars; content might be clipped. (AR_DVAL_VIEWFIELD_SCROLLBARS_HIDDEN).

  • AR_DPROP_VISIBLE (ENUM): A flag that indicates the visibility of the field. Valid values for this property are 0 (hidden) and 1 (visible). The default value is 1 (visible). For control fields, this setting applies to all specified screen appearances (see AR_DPROP_CNTL_TYPE).
  • AR_DPROP_Z_ORDER (unsigned long): A value that determines the field drawing order. The value associated with each field in a form view (VUI) determines the back-to-front layering of the fields on the screen (from lowest to highest). The Z-order values of all fields associated with a given view must be unique. If two or more fields have duplicate Z-order values, the system orders them at random.

    Note

    BMC Remedy Mid Tier displays table fields, panel holder fields, and buttons with images in front of other fields regardless of their Z-order.

See also

ARCreateVUI, ARDeleteField, ARGetField, ARGetMultipleFields, ARGetListField, ARSetField. See FreeAR for: FreeARFieldLimitList, FreeARPermissionList, FreeARStatusList, FreeARValueStruct.

Was this page helpful? Yes No Submitting... Thank you

Comments