Multi-line Text Item

The multi-line text item allows editable multi-line text strings to be entered. Vertical scrolling is supported. The user controls vertical scrolling by using a scroll bar that is part of the multi-line text item. When the user presses the Enter key, a line break is entered. The standard cut, copy and paste operations are supported. Selecting of multiple characters can be done by dragging the mouse cursor through ranges of text, and by performing keyboard navigation with the shift key held down

Both word-wrap and horizontal scrolling are supported, although they are mutually exclusive. One or the other must be selected as part of the item definition.

If no-wrap is specified in the item definition, then horizontal scrolling is used. The user controls horizontal scrolling by moving the cursor. If the user tries to move the cursor out of the display area, then MicroStation scrolls the text so that the cursor remains in the display area. Since the user must use the cursor to control horizontal scrolling, this option is not useful for read-only multi-line text items.

If no-wrap is not specified, then word wrap is supported and horizontal scrolling is not supported. If a line exceeds the item's display area, the display is word wrapped at a break.

Multi-line text items used to display a lot of text should use horizontal scrolling since this is more efficient than word wrap. This should not be an issue for most applications.

See the "Text Item Functions" section of the "Dialog Box Manager" chapter of the MDL Function Reference Manual for more information.

Item list specification

The field origin in the DialogItemRsc field extent specifies the origin of the beveled rectangle that contains the text to edit. The field width in the DialogItemRsc field extent specifies the distance from left-most boundary of the left-most bevel, to the right-most pixel of the right-most bevel. The field height in the DialogItemRsc field extent is ignored. The actual height of the item is computed based on the DItem_MultilineTextRsc field displayRows. If a label is associated with the multi-line text item, it may be displayed above the item or to the left of the item. In either case, the label does not affect the positioning of the bevel. If the label is displayed to the left, then the origin of the label is computed as follows: the x coordinate is set to the origin of the bevel minus the width of the string minus the width of an average character; the y coordinate is set to the y coordinate of the bevel origin plus 2. The top of the label lines up with the bottom edge of the top bevel and there is a gap approximately 1 character long between the end of the label and the bevel. If the label is displayed above, then the origin of the label is computed as follows: the x coordinate is the same as the x coordinate of the origin of the bevel; the y coordinate is set to the y coordinate of the origin minus the character height minus one quarter of the character height.

The type field should be set to MLText.

The ID determines the DItem_MultilineTextRsc instance to load.

The attributes field can be ON or OFF and optionally combined with HIDDEN. It will usually be ON.

The itemArg field may be set to TEXT_MASK_LABELABOVE to specify that the label should appear above the beveled rectangle. Otherwise, itemArg should usually be set to 0.

The label field can override the label contained in the DItem_MultilineTextRsc instance.

The following is an example of a text item list specification:

{{XC, YC, 40*XC, 0}, MLText, MLTEXTID_TextEdit, ON, 0, "", ""}

Item resource specification

The multi-line text item is defined in a resource file with the following structure:

typedef struct ditem_multilinetextrsc
{
    long synonymsId;
    ULong helpInfo;
    ULong helpSource;
    long itemHookId;
    long itemHookArg;
    UShort attributes;          // other attributes
    long displayRows;
#if defined (resource) 
    char label[];
#else 
    long labelLength;
    char label[1];
#endif 
} DItem_MultilineTextRsc;

The DItem_MultilineTextRsc structure has the following unique fields. (See "Common item resource fields" for a description of any field not in this table).

Field	Description
displayRows	The number of rows to be displayed inside the beveled rectangle.
attributes	A short integer that specifies text item characteristics. It is constructed by combining the constants from the following table with the logical OR operator.

attributes Value	Meaning
MLTEXTATTR_READONLY	This forces the field to be read-only. With this in effect, the field never accepts the focus. It is impossible to enter characters into the field, or to position the text cursor to the field. The scroll bar associated with the dialog box still accepts the focus, so a user may use it to scroll through text that has too many lines to be displayed at once.
MLTEXTATTR_NODISPLAYNLCHAR	By default, MicroStation always displays an end-of-line marker at the end of each line. This lets the user distinguish between a line wrap and the actual end of a line. If the MLTEXTATTR_NODISPLAYNLCHAR attribute is specified, MicroStation never displays the end-of-line marker.
MLTEXTATTR_AUTOHIDEDECOR	By default, MicroStation always displays the beveled border and scroll bar associated with a multi-line text item. If the MLTEXTATTR_AUTOHIDEDECOR attribute is specified along with the MLTEXTATTR_READONLY attribute, MicroStation will not display the bounding box and scroll bar unless the text enclosed in the item is large enough to warrant their existence.
MLTEXTATTR_ALWAYSBEVELED	This attribute is used to override part of the effects of the MLTEXTATTR_AUTOHIDEDECOR attribute. If the MLTEXTATTR_ALWAYSBEVELED attribute is specified along with the MLTEXTATTR_READONLY and MLTEXTATTR_AUTOHIDEDECOR attributes, MicroStation will always display the beveled border surrounding the multi-line text.
MLTEXTATTR_NOWRAP	This attribute turns off the default auto line wrap processing of the multi-line item handler. Using this attribute causes horizontal scrolling to be used instead of wrapping text to the next display line.
MLTEXTATTR_FIXEDFONT	This attribute is used to cause MicroStation to display the text in the multi-line text item in the fixed width display font. A proportional font, which is usually preferred, will be used if this is not defined.
MLTEXTATTR_SBARINWIDTH	Indicates item width includes vertical scroll bar width.

The following is an example of a multi-line text item resource.

DItem_MultilineTextRsc MLTEXTID_MlTxtEdit1=
{
    NOSYNONYM, NOHELP, MHELP, HOOKITEMID_EditMlTxt, 1,
    0, MLTXT_EDIT_LINES, ""
};

Item hook function messages

The following messages are sent to item hook functions that are attached to text items:

  DITEM_MESSAGE_CREATE
  DITEM_MESSAGE_INIT
  DITEM_MESSAGE_DESTROY
  DITEM_MESSAGE_SYNCHRONIZE
  DITEM_MESSAGE_FOCUSIN
  DITEM_MESSAGE_FOCUSOUT
  DITEM_MESSAGE_KEYSTROKE
  DITEM_MESSAGE_POSTKEYSTROKE
  DITEM_MESSAGE_GETSTATE
  DITEM_MESSAGE_SETSTATE

An MDL program can provide the multi-line text string to MicroStation either by having an item hook handler respond to a DITEM_MESSAGE_GETSTATE message, or by calling mdlDialog_itemSetValue. For the DITEM_MESSAGE_GETSTATE message, the hook handler must set the field stringValueP of the value structure to point to the string. When using mdlDialog_itemSetValue, the MDL program uses the stringValueP parameter to provide a pointer to the string. In either case, MicroStation makes a copy of the string and operates on the internal copy.

An MDL program can retrieve the multi-line text string from MicroStation either by having an item hook handler respond to a DITEM_MESSAGE_SETSTATE message, or by calling mdlDialog_itemGetValue. For the DITEM_MESSAGE_SETSTATE message, the field stringValueP of the value structure points to MicroStation's copy of the string. The mdlDialog_itemGetValue function sets valueUnionP->charPFormat to point to MicroStation's copy of the string. The MDL program must not modify MicroStation's copy of the string.

The multi-line text string passed between MicroStation and the MDL program is one string with the line breaks marked by a special character. The value of this character is defined in the built-in variable textNLCharacter.

Multi-line text uses the standard new line character `
' that is represented in C. Compatibility with older MDL applications that used textNLCharacter for line breaks will be maintained, as textNLCharacter will be defined as `\n.'

Multi-line Text item functions

Funtion	Description
mdlDialog_mlTextGetInfo	retrieves detailed information about a multi-text item.
mdlDialog_mlTextSetInfo	sets various aspects of a multi-text item.
mdlDialog_mlTextGetCursor	returns the line number and position of the cursor.
mdlDialog_mlTextSetCursor	sets the position of the cursor or highlight range.
mdlDialog_mlTextGetLineCoords	translates a cursor position into a line number and offset.
mdlDialog_mlTextGetLineRange	gets the range in bytes of a line in the text buffer.
mdlDialog_mlTextInsertString	inserts a string into the buffer.
mdlDialog_mlTextTopRowNumber	gets the number of the line being displayed in position zero.