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

ss06.jpg

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.

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 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.

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.