Dialog Box Items

Modules
	Button Group Item
	Color Chooser Item
	Color Picker Item
	ComboBox Item
	Container Item
	ContainerPanelItem
	Icon and IconCommand
	Icon and IconFrame
	IconPopupItem
	Label Item
	LevelList Item
	ListBox Item
	MenuBar Item
	LineText Item
	OptionButton Item
	Option Pulldown Menu Item
	PushButton Item
	RadioButton Item
	SashItem
	ScaleItem
	ScrollBar Item
	SpinBox Item
	TabPageList Item
	Text Item
	TextPull-downMenu Item
	ToolBox Item
	ToggleButton Item
	ToggleIcon Item
	Tree Item
	UpDownButtons Item

Functions
int	mdlDialog_focusItemIndexGet (MSDialogP dbP)
	Retrieves the index of the dialog item which currently has the keyboard focus in the specified Dialog Box. More...
StatusInt	mdlDialog_focusItemIndexSet (MSDialogP dbP, int iItem, bool ignoreFocusOutErrors)
	Sets the keyboard focus item in the specified Dialog Box. More...
StatusInt	mdlDialog_itemDraw (MSDialogP dbP, int iItem)
	Redraws an item within the Dialog Box specified by dbP. More...
StatusInt	mdlDialog_itemDrawEx (MSDialogP dbP, int iItem, bool eraseFirst)
	An extension of mdlDialog_itemDraw with the added eraseFirst argument. More...
DialogItem *	mdlDialog_itemGetByIndex (MSDialogP dbP, int itemIndex)
	Retrieves a pointer to the requested dialog item contained in the specified Dialog Box. More...
DialogItem *	mdlDialog_itemGetByTypeAndId (MSDialogP dbP, RscType type, RscId id, int startingIndex)
	Retrieves a pointer to the dialog item of type and resource ID id that is contained in the specified Dialog Box. More...
DialogItem *	mdlDialog_itemGetByTypeAndIdEx (MSDialogP dbP, RscType type, RscId id, MdlDescP ownerMD, int startingIndex, bool searchChildren)
	Retrieves a pointer to the dialog item of type and resource ID id that is contained in the specified Dialog Box. More...
DialogItem *	mdlDialog_itemGetByTypeAndIndex (MSDialogP dbP, RscType type, int index)
	Gets a DialogItem by the type and an index within the items of that type. More...
StatusInt	mdlDialog_itemGetState (MSValueDescrR itemValue, MSDialogP dbP, int iItem)
	Retrieves the specified Dialog Box item's external state. More...
StatusInt	mdlDialog_itemGetValue (MSValueDescrR itemValue, MSDialogP dbP, int iItem)
	Retrieves the specified Dialog Box item's internal value. More...
StatusInt	mdlDialog_itemGetStringValue (WStringR valueString, MSDialogP dbP, int iItem)
	Retrieves the specified Dialog Box item's internal value as a string. More...
StatusInt	mdlDialog_itemHide (MSDialogP dbP, int iItem, bool ignoreFocusOutErrors)
	Hides an item within the Dialog Box db. More...
DialogItem *	mdlDialog_itemLoad (MSDialogP dbP, DialogItemRsc *diRP, RscFileHandle rFileH, MdlDescP ownerMD, int beforeItemIndex, Point2dP originP)
	Loads the item specified by data pointed at by diRP into the specified Dialog Box. More...
StatusInt	mdlDialog_itemMove (MSDialogP dbP, int iItem, Point2dP ptP, bool redraw)
	Moves an item within the specified Dialog Box. More...
StatusInt	mdlDialog_itemSetCancel (MSDialogP dbP, int iItem)
	Sets a new GUI item as the cancel item. More...
StatusInt	mdlDialog_itemSetDefault (MSDialogP dbP, int iItem)
	Sets a new GUI item as the default action item. More...
StatusInt	mdlDialog_itemSetEnabledState (MSDialogP dbP, int iItem, bool enabled, bool ignoreFocusOutErrors)
	Sets the enabled state (enabled or disabled) of an item within the specified Dialog Box. More...
StatusInt	mdlDialog_itemSetExtent (MSDialogP dbP, int iItem, SextentCP sextentP, bool redraw)
	Sets the extent of an item within the dialog box specified by dbP. More...
StatusInt	mdlDialog_itemSetLabel (MSDialogP dbP, int iItem, WCharCP pwString)
	Sets the label of an item within the dialog box specified by dbP. More...
StatusInt	mdlDialog_itemSetState (bool *stateChangedP, MSDialogP dbP, int iItem)
	Forces the specified Dialog Box item's external state to match its internal value. More...
StatusInt	mdlDialog_itemSetValue (bool *valueChangedP, MSValueDescrCR itemValue, MSDialogP dbP, int iItem)
	Sets the internal value of the specified Dialog Box item to a certain value. More...
StatusInt	mdlDialog_itemSetStringValue (bool *valueChangedP, WCharCP stringValueP, MSDialogP dbP, int iItem)
	A helper function to set the internal value of the specified Dialog Box item to a string value. More...
StatusInt	mdlDialog_itemShow (MSDialogP dbP, int iItem)
	Shows a previously hidden item within the specified Dialog Box. More...
StatusInt	mdlDialog_itemSynch (MSDialogP dbP, int iItem)
	Forces the appearance of an item to match its external state. More...
StatusInt	mdlDialog_itemSynchByTypeAndId (MSDialogP dbP, RscType itemType, RscId itemId)
	Causes a DITEM_MESSAGE_SYNCHRONIZE message to be sent to the dialog item indicated by itemType and itemId in the Dialog Box indicated by dbP. More...
StatusInt	mdlDialog_itemSynchOthers (RawItemHdrP riP)
	Causes a DITEM_MESSAGE_SYNCHRONIZE message to be sent to all items listed in the synonym list indicated for the item indicated by riP. More...
BSIColorDescrP	mdlDialog_itemGetColor (MSDialogP dbP, int iItem, int itemColorType)
	Gets a specific color for the item indicated by riP. More...
StatusInt	mdlDialog_itemSetColor (MSDialogP dbP, int iItem, int itemColorType, BSIColorDescrP colorP)
	Sets a specific color for the item indicated by riP. More...
int	mdlDialog_findItemIndex (MSDialogP dbP, Point2dP ptP, bool ignoreEnabledStatus)
	Retrieves a pointer to the dialog item located at the location specified by ptP. More...
StatusInt	mdlDialog_itemReloadData (MSDialogP dbP, int iItem, bool redraw)
	Reloads the item information for one Dialog Box item. More...
StatusInt	mdlDialog_itemsApply (MSDialogP dbP)
	Forces the external state of all enabled items in the specified Dialog Box to match their appearance. More...
StatusInt	mdlDialog_itemsAttach (MSDialogP dbP, int nToInsert, DialogItem **diPListPP, int beforeItemIndex, bool drawItems)
	Attaches dialog items from a DialogItem array into the specified Dialog Box. More...
StatusInt	mdlDialog_itemsDetach (MSDialogP dbP, int startItemIndex, int maxItemIndex, bool eraseItems)
	Detaches dialog items from a MSDialog's item list. More...
StatusInt	mdlDialog_itemsFree (MSDialogP dbP, int startItemIndex, int maxItemIndex)
	Frees all the specified dialog items from the specified Dialog Box. More...
int	mdlDialog_itemsGetNumberOf (MSDialogP dbP)
	Retrieves the number of dialog items contained by the specified Dialog Box. More...
StatusInt	mdlDialog_itemsLoad (MSDialogP dbP, DialogItemListRsc *dilRP, RscFileHandle rFileH, MdlDesc *ownerMD, int beforeItemIndex, Point2dP originP, bool drawItems)
	Loads the items specified by data pointed at by dilRP into the specified Dialog Box. More...
StatusInt	mdlDialog_itemsSwapOrder (MSDialogP dbP, int itemIndex1, int itemIndex2)
	Swaps the positions of two dialog items in a Dialog Box. More...
StatusInt	mdlDialog_itemsSynch (MSDialogP dbP)
	Forces the appearance of all items in the Dialog Box specified by dbP to match their external state. More...
StatusInt	mdlDialog_itemsObscure (MSDialogP dbP, int iStartItem, int iEndItem, bool doObscure)
	Obscures (hides) or unobscures items on the dialog specified by dbP and sets/unsets the attributes.obscured flag. More...
void	mdlDialog_itemsAdjustWithSash (MSDialogP dbP, BSIRectP pNewContent, BSIRectP pOldContent, AdjustItem *pSashItem, AdjustItem *pTopLeftItem, AdjustItem *pBottomRightItem)
	Adjusts (moves and resizes) items, according to settings in the AdjustItem parameters, on a MSDialog that contains a Sash item. More...
void	mdlDialog_itemsAdjustFlushWithSash (MSDialogP dbP, BSIRectP pNewContent, BSIRectP pOldContent, DialogItem *pSashItem, DialogItem *pTopLeftItem, bool bTopLeftErase, bool bTopLeftFullRedraw, DialogItem *pBottomRightItem, bool bBottomRightErase, bool bBottomRightFullRedraw)
	Simlar to mdlDialog_itemsAdjustWithSash in that it adjusts (moves and resizes) items on a MSDialog that contains a Sash item. More...

Detailed Description

Function Documentation

int mdlDialog_findItemIndex	(	MSDialogP	dbP,
		Point2dP	ptP,
		bool	ignoreEnabledStatus
	)

Retrieves a pointer to the dialog item located at the location specified by ptP.

Parameters

[in]	dbP	MSDialog that contains item to find
[in]	ptP	pointer to a Point2d containing the local coordinates of the item to find
[in]	ignoreEnabledStatus	indicates whether to find an item even if it is disabled

Returns

The index of the item found or INVALID_ITEM if an item is not found.

See also

mdlDialog_itemGetByIndex mdlDialog_itemGetByTypeAndId

Remarks

Required Library: mdlbltin.lib

int mdlDialog_focusItemIndexGet

(

MSDialogP

dbP

)

Retrieves the index of the dialog item which currently has the keyboard focus in the specified Dialog Box.

Note that the item will only actually have the keyboard focus if the Dialog Box has the focus. Otherwise, it is the item which will gain the focus the next time the Dialog Box becomes the keyboard focus Dialog Box.

Parameters

[in]

dbP

MSDialog whose focus we're getting Remarks mdlDialog_focusItemIndexSet will not let you set the focus to a specific item on a DITEM_MESSAGE_FOCUSOUT; attempting to do so will put you into a focus out loop. Instead, you should set nextFocusItemIndex in the dialog item message structure to the index of the item you want the focus to be in. For example: case DITEM_MESSAGE_FOCUSOUT: u.focusOut.nextFocusItemIndex = 4

Returns

The index of the item that currently has the keyboard focus. It returns -1 if no item within the Dialog Box has the focus.

See also

mdlDialog_itemsGetNumberOf mdlDialog_focusItemIndexSet

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_focusItemIndexSet	(	MSDialogP	dbP,
		int	iItem,
		bool	ignoreFocusOutErrors
	)

Sets the keyboard focus item in the specified Dialog Box.

When the Dialog Box is the keyboard focus Dialog Box, that item will receive user keystrokes.

Parameters

[in]	dbP	MSDialog we're setting
[in]	iItem	parameter specifies the new keyboard focus item index. itemIndex must be greater than or equal to 0 and less than the number of items in the Dialog Box. Use the mdlDialog_itemsGetNumberOf function to determine the number of items in a Dialog Box. The type of item specified must be able to accept user keystrokes.
[in]	ignoreFocusOutErrors	parameter can be used to ignore any errors (such as the current value being out of range) that may occur when taking the focus away from the current focus item. It should usually be set to false which indicates that focus out errors should not be ignored.

Returns

SUCCESS, or ERROR if dbP is not a pointer to a Dialog Box, or itemIndex is out of range, or the focus can not be removed from the current focus item. Remarks mdlDialog_focusItemIndexSet will not let you set the focus to a specific item on a DITEM_MESSAGE_FOCUSOUT; attempting to do so will put you into a focus out loop. Instead, you should set nextFocusItemIndex in the dialog item message structure to the index of the item you want the focus to be in. For example: case DITEM_MESSAGE_FOCUSOUT: u.focusOut.nextFocusItemIndex = 4

See also

mdlDialog_itemsGetNumberOf mdlDialog_focusItemIndexGe

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemDraw	(	MSDialogP	dbP,
		int	iItem
	)

Redraws an item within the Dialog Box specified by dbP.

The item is drawn based on its internal value, not its external state.

Parameters

[in]	dbP	MSDialog that contains the item to draw
[in]	iItem	specifies the index of the item to draw. itemIndex must be greater than or equal to 0 and less than the number of items in the dialog box. Use the mdlDialog_itemsGetNumberOf function to determine the number of items in a Dialog Box.

Remarks

Hidden items can not be drawn. Call mdlDialog_itemShow to draw hidden items. Whether an item is hidden or not can be determined by looking at the item's DialogItem attributes.hidden bit.

Returns

SUCCESS, or ERROR if an error occurs, which means that dbP is not a pointer to a Dialog Box or itemIndex is out of range. db is not a pointer to a Dialog Box or iItem is out of range.

See also

mdlDialog_itemsGetNumberOf mdlDialog_itemGetByIndex mdlDialog_itemGetByTypeAndId

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemDrawEx	(	MSDialogP	dbP,
		int	iItem,
		bool	eraseFirst
	)

An extension of mdlDialog_itemDraw with the added eraseFirst argument.

Redraws an item within the Dialog Box specified by dbP. The item is drawn based on its internal value, not its external state.

Parameters

[in]	dbP	MSDialog that contains the item to draw
[in]	iItem	item index of the item to draw
[in]	eraseFirst	indicates whether to erase the item first before redrawing

Returns

SUCCESS, or ERROR if an error occurs, which means that dbP is not a pointer to a Dialog Box or itemIndex is out of range.

See also

mdlDialog_itemDraw

Remarks

Required Library: mdlbltin.lib

DialogItem* mdlDialog_itemGetByIndex	(	MSDialogP	dbP,
		int	itemIndex
	)

Retrieves a pointer to the requested dialog item contained in the specified Dialog Box.

Parameters

[in]	dbP	MSDialog that contains the item
[in]	itemIndex	parameter specifies the index of the item to retrieve a pointer to. itemIndex must be greater than or equal to 0, and less than the number of items in the Dialog Box. Use the mdlDialog_itemsGetNumberOf function to determine the number of items in a Dialog Box.

Remarks

Generally speaking, to make an MDL application more robust, pointers to items should be obtained by calling the mdlDialog_itemGetByTypeAndId function, not mdlDialog_itemGetByIndex. In this way, the application does not depend on items being in fixed positions within the dialog item list. New items can be added at the beginning or items removed from the middle of a dialog without affecting program code. Since the dialog item list is searched for the specified item, its position can change if mdlDialog_itemGetByTypeAndId is used.

A number of other Dialog Box functions require item indexes. To make an application more item position independent when an item index is required, first call mdlDialog_itemGetByTypeAndId, and then use the pointer that is returned to determine the item index of the item that is found. For example:

{
...
DialogItem *diP;
int itemIndex;
RawItemHdr *textP;
diP=mdlDialog_itemGetByTypeAndId(db, RTYPE_Text,
                                 TEXTID_ElementColor,0);
itemIndex=diP->itemIndex;
textP=diP->rawItemP;
...
}

A number of other Dialog Box functions require a pointer to a RawItemHdr structure not a pointer to a DialogItem structure. The above example also shows how to get a pointer to a RawItemHdr given a pointer to a DialogItem.

Pointers to DialogItem structures or RawItemHdr structures will remain valid as long as the referenced item exists. The pointers will be valid even if other items are inserted or deleted from the Dialog Box. A pointer to a DialogItem that is retrieved when the item is first created, (obtained upon response to the DITEM_MESSAGE_CREATE message) will be valid until the item is destroyed.

Returns

A pointer to a DialogItem structure, or NULL if the specified item is not found.

See also

mdlDialog_itemsGetNumberOf mdlDialog_itemGetByTypeAndId

Remarks

Required Library: mdlbltin.lib

DialogItem* mdlDialog_itemGetByTypeAndId	(	MSDialogP	dbP,
		RscType	type,
		RscId	id,
		int	startingIndex
	)

Retrieves a pointer to the dialog item of type and resource ID id that is contained in the specified Dialog Box.

The list of possible values for type is contained in dlogbox.r.h. For example, the type of a text item is RTYPE_Text.

Parameters

[in]	dbP	MSDialog that contains item
[in]	type	type of item to get
[in]	id	parameter specifies the resource id of the item to retrieve a pointer to.
[in]	startingIndex	parameter specifies where to start looking for the dialog item. It is usually set to 0, which means start the search from the beginning of the dialog item list.

Remarks

Generally speaking, to make an MDL application more robust, pointers to items should be obtained by calling the mdlDialog_itemGetByTypeAndId function, not mdlDialog_itemGetByIndex. In this way, the application does not depend on items being in fixed positions within the dialog item list. New items can be added at the beginning or items removed from the middle of a dialog without affecting program code. Since the dialog item list is searched for the specified item, its position can change if mdlDialog_itemGetByTypeAndId is used.

A number of other Dialog Box functions require item indexes. To make an application more item position independent when an item index is required, first call mdlDialog_itemGetByTypeAndId, and then use the pointer that is returned to determine the item index of the item that is found. For example:

{
...
DialogItem *diP;
int itemIndex;
RawItemHdr *textP;
diP=mdlDialog_itemGetByTypeAndId(db, RTYPE_Text,
                                 TEXTID_ElementColor,0);
itemIndex=diP->itemIndex;
textP=diP->rawItemP;
...
}

A number of other Dialog Box functions require a pointer to a RawItemHdr structure not a pointer to a DialogItem structure. The above example also shows how to get a pointer to a RawItemHdr given a pointer to a DialogItem.

Pointers to DialogItem structures or RawItemHdr structures will remain valid as long as the referenced item exists. The pointers will be valid even if other items are inserted or deleted from the Dialog Box. A pointer to a DialogItem that is retrieved when the item is first created, (obtained upon response to the DITEM_MESSAGE_CREATE message) will be valid until the item is destroyed.

Returns

A pointer to a DialogItem structure, or NULL if the specified item is not found.

See also

mdlDialog_itemsGetNumberOf mdlDialog_itemGetByIndex

Remarks

Required Library: mdlbltin.lib

DialogItem* mdlDialog_itemGetByTypeAndIdEx	(	MSDialogP	dbP,
		RscType	type,
		RscId	id,
		MdlDescP	ownerMD,
		int	startingIndex,
		bool	searchChildren
	)

Retrieves a pointer to the dialog item of type and resource ID id that is contained in the specified Dialog Box.

The list of possible values for type is contained in dlogbox.r.h. For example, the type of a text item is RTYPE_Text.

Parameters

[in]	dbP	MSDialog that contains item
[in]	type	type of item to get
[in]	id	parameter specifies the resource id of the item to retrieve a pointer to.
[in]	ownerMD	owner of item, NULL means owner of parent
[in]	startingIndex	parameter specifies where to start looking for the dialog item. It is usually set to 0, which means start the search from the beginning of the dialog item list.
[in]	searchChildren	parameter specifies whether or not to search children.

Returns

A pointer to a DialogItem structure, or NULL if the specified item is not found.

See also

mdlDialog_itemsGetNumberOf mdlDialog_itemGetByIndex

Remarks

Required Library: mdlbltin.lib

DialogItem* mdlDialog_itemGetByTypeAndIndex	(	MSDialogP	dbP,
		RscType	type,
		int	index
	)

Gets a DialogItem by the type and an index within the items of that type.

Parameters

[in]	dbP	MSDialog that contains item
[in]	type	type of the item to get
[in]	index	index within the items of that type

Returns

A pointer to a DialogItem structure, or NULL if the specified item is not found.

Remarks

Required Library: mdlbltin.lib

BSIColorDescrP mdlDialog_itemGetColor	(	MSDialogP	dbP,
		int	iItem,
		int	itemColorType
	)

Gets a specific color for the item indicated by riP.

Parameters

[in]	dbP	MSDialog that contains item to process
[in]	iItem	specifies the index of the item to get the color from. iItem must be greater than or equal to 0, and less than the number of items in the dialog box. Use mdlDialog_itemsGetNumberOf to determine the number of items in a Dialog Box.
[in]	itemColorType	one of the color types beginning with "DITEM_COLORTYPE_" defined in msdefs.h.

Returns

A pointer to a BSIColorDescr, or NULL is dbP or iItem is invalid.

See also

mdlDialog_itemSetColor mdlDialog_itemsGetNumberOf

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemGetState	(	MSValueDescrR	itemValue,
		MSDialogP	dbP,
		int	iItem
	)

Retrieves the specified Dialog Box item's external state.

This is the value of the application data that the item controls, possibly filtered through a mask associated with the item.

Parameters

[in,out]	itemValue	specifies the MSValueDescr to receive the value. The MSValueDescr struct provides methods to query the type of data and methods to get the data.
[in]	dbP	parameter specifies a Dialog Box.
[in]	iItem	parameter specifies the index of the item whose external state or internal value the function is retrieving. itemIndex must be greater than or equal to 0 and less than the number of items in the Dialog Box. Use mdlDialog_itemsGetNumberOf to determine the number of items in a Dialog Box.

Returns

SUCCESS or ERROR. occurs. Either dbP doesn't point to a Dialog Box, or iItem is out of range.

See also

mdlDialog_itemsGetNumberOf mdlDialog_itemGetValue

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemGetStringValue	(	WStringR	valueString,
		MSDialogP	dbP,
		int	iItem
	)

Retrieves the specified Dialog Box item's internal value as a string.

This is the value that is used to determine the item's appearance when the item is drawn.

Parameters

[out]	valueString	specifies the WString to receive the value.
[in]	dbP	parameter specifies a Dialog Box.
[in]	iItem	parameter specifies the index of the item whose external state or internal value the function is retrieving. iItem must be greater than or equal to 0 and less than the number of items in the Dialog Box. Use mdlDialog_itemsGetNumberOf to determine the number of items in a Dialog Box.

Returns

SUCCESS, or ERROR if dbP doesn't point to a Dialog Box, or iItem is out of range.

See also

mdlDialog_itemsGetNumberOf mdlDialog_itemGetState

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemGetValue	(	MSValueDescrR	itemValue,
		MSDialogP	dbP,
		int	iItem
	)

Retrieves the specified Dialog Box item's internal value.

This is the value that is used to determine the item's appearance when the item is drawn.

Parameters

[in,out]	itemValue	specifies the MSValueDescr to receive the value. The MSValueDescr struct provides methods to query the type of data and methods to get the data.
[in]	dbP	parameter specifies a Dialog Box.
[in]	iItem	parameter specifies the index of the item whose external state or internal value the function is retrieving. iItem must be greater than or equal to 0 and less than the number of items in the Dialog Box. Use mdlDialog_itemsGetNumberOf to determine the number of items in a Dialog Box.

Returns

SUCCESS, or ERROR if dbP doesn't point to a Dialog Box, or iItem is out of range.

See also

mdlDialog_itemsGetNumberOf mdlDialog_itemGetState

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemHide	(	MSDialogP	dbP,
		int	iItem,
		bool	ignoreFocusOutErrors
	)

Hides an item within the Dialog Box db.

Parameters

[in]	dbP	MSDialog that contains item to hide
[in]	iItem	specifies the index of the item to hide. itemIndex must be greater than or equal to 0, and less than the number of items in the dialog box. Use the mdlDialog_itemsGetNumberOf function to determine the number of items in a Dialog Box.
[in]	ignoreFocusOutErrors	parameter can be used to ignore any focusing out errors (such as the current value being out of range) that may occur if the item to be hidden has the keyboard focus. It should usually be set false, which indicates that focus out errors should not be ignored.

Remarks

Whether an item is hidden or not can be determined by looking at the item's DialogItem attributes.hidden bit.

Returns

SUCCESS, or ERROR if db is not a pointer to a Dialog Box, itemIndex is out of range, or the item has the focus and the focus can not be removed (because the current value is out of range).

See also

mdlDialog_itemShow mdlDialog_itemsGetNumberOf mdlDialog_itemGetByIndex mdlDialog_itemGetByTypeAndId

Remarks

Required Library: mdlbltin.lib

DialogItem* mdlDialog_itemLoad	(	MSDialogP	dbP,
		DialogItemRsc *	diRP,
		RscFileHandle	rFileH,
		MdlDescP	ownerMD,
		int	beforeItemIndex,
		Point2dP	originP
	)

Loads the item specified by data pointed at by diRP into the specified Dialog Box.

Parameters

[in]	dbP	MSDialog to contain item
[in]	diRP	parameter points to a DialogItemRsc structure that specifies the item to load. The fields of the DialogItemRsc structure should be set just as if a definition in a resource file were being created.
[in]	rFileH	parameter specifies the resource file to search for the dialog box item resource. If NULL, all the calling application's open resource files, then MicroStation's open resource files will be searched.
[in]	ownerMD	parameter should be set to NULL.
[in]	beforeItemIndex	parameter specifies the index of the item before which the new item will be loaded. Specify -1 to indicate that the item should be appended at the end of the dialog item list.
[in]	originP	parameter is used to specify the origin of a temporary coordinate system that will be used when loading the dialog item. The units of the point pointed at by originP should be in dialog coordinate units. The extent field of the DialogItemRsc structure pointed at by diRP will be interpreted with an origin at originP. Specify NULL for originP to indicate the origin should be at (0, 0), the upper left corner of the dialog box.

Returns

A pointer to the dialog item that is loaded or NULL if an error occurs. This means that dbP is not a pointer to a dialog box or the item resource could not be found.

See also

mdlDialog_itemsLoad

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemMove	(	MSDialogP	dbP,
		int	iItem,
		Point2dP	ptP,
		bool	redraw
	)

Moves an item within the specified Dialog Box.

Parameters

[in]	dbP	MSDialog that contains item to move
[in]	iItem	specifies the index of the item to move. itemIndex must be greater than or equal to 0, and less than the number of items in the dialog box. Use mdlDialog_itemsGetNumberOf to determine the number of items in a Dialog Box.
[in]	ptP	parameter points at a variable that specifies the new location of the item. Positive values for the x or y member of Point2d indicate that dialog coordinate units are being specified. Negative values should be used to specify the new location in pixels. In general, pixel coordinates should be avoided since problems may occur if the Dialog Box is moved to a screen that uses a different text font size.
[in]	redraw	if parameter is true, the item will be drawn in its new location.

Returns

SUCCESS, or ERROR if dbP is not a pointer to a Dialog Box or iItem is out of range.

See also

mdlDialog_itemsGetNumberOf

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemReloadData	(	MSDialogP	dbP,
		int	iItem,
		bool	redraw
	)

Reloads the item information for one Dialog Box item.

Parameters

[in]	dbP	is the dialog that contains the item to reload.
[in]	iItem	is the index of the item to reload.
[in]	redraw	indicates whether the item should be redrawn to the screen after reloading the item information.

Returns

SUCCESS or ERROR.

See also

mdlDialog_itemDraw

Remarks

Required Library: mdlbltin.lib

void mdlDialog_itemsAdjustFlushWithSash	(	MSDialogP	dbP,
		BSIRectP	pNewContent,
		BSIRectP	pOldContent,
		DialogItem *	pSashItem,
		DialogItem *	pTopLeftItem,
		bool	bTopLeftErase,
		bool	bTopLeftFullRedraw,
		DialogItem *	pBottomRightItem,
		bool	bBottomRightErase,
		bool	bBottomRightFullRedraw
	)

Simlar to mdlDialog_itemsAdjustWithSash in that it adjusts (moves and resizes) items on a MSDialog that contains a Sash item.

However, the items on either side of the Sash item are adjusted to be flush with the Sash item with no buffer. This function can be useful during a dialog resize to adjust positions and sizes of items to fit the size of the dialog.

Parameters

[in]	dbP	dialog to process
[in]	pNewContent	rectangle representing the new content rectangle of the dialog in local coordinates
[in]	pOldContent	rectangle representing the old content rectangle of the dialog in local coordinates
[in]	pSashItem	Sash item pointer.
[in]	pTopLeftItem	item pointer of the item on top of, or to the left of, the Sash item.
[in]	bTopLeftErase	indicates whether to erase the item before adjusting it.
[in]	bTopLeftFullRedraw	indicates whether to draw the entire item or only the part of the item that changed.
[in]	pBottomRightItem	item pointer of the item on bottom of, or to the right of, the Sash item.
[in]	bBottomRightErase	indicates whether to erase the item before adjusting it.
[in]	bBottomRightFullRedraw	indicates whether to draw the entire item or only the part of the item that changed.

See also

mdlDialog_itemsAdjustWithSash

Remarks

Required Library: mdlbltin.lib

void mdlDialog_itemsAdjustWithSash	(	MSDialogP	dbP,
		BSIRectP	pNewContent,
		BSIRectP	pOldContent,
		AdjustItem *	pSashItem,
		AdjustItem *	pTopLeftItem,
		AdjustItem *	pBottomRightItem
	)

Adjusts (moves and resizes) items, according to settings in the AdjustItem parameters, on a MSDialog that contains a Sash item.

This function can be useful during a dialog resize to adjust positions and sizes of items to fit the size of the dialog.

Parameters

[in]	dbP	dialog to process
[in]	pNewContent	rectangle representing the new content rectangle of the dialog in local coordinates
[in]	pOldContent	rectangle representing the old content rectangle of the dialog in local coordinates
[in]	pSashItem	AdjustItem parameters for the Sash item.
[in]	pTopLeftItem	AdjustItem parameters for item on top of, or to the left of, the Sash item.
[in]	pBottomRightItem	AdjustItem parameters for item on bottom of, or to the right of, the Sash item.

Remarks

The AdjustItem structure has the following format:

struct AdjustItem
   {
   DialogItemP     pDialogItem;
   BSIRectP        pBufferRect;
   bool            bEraseItem;
   bool            bFullRedraw;
   };

Use the four variables in the pBufferRect rectangle to indicate the amount of space to not use around the particular item. For example, if the following code is used, 10 pixels on the left and right and and 5 pixels on the top and bottom will not be used and will result in a buffer around the item:

topLeftItemRect.origin.x = 10;
topLeftItemRect.origin.y = 5;
topLeftItemRect.origin.x = 10;
topLeftItemRect.origin.x = 5;

bEraseItem indicates whether to erase the item before adjusting it. bFullRedraw indicates whether to draw the entire item or only the part of the item that changed.

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemsApply

(

MSDialogP

dbP

)

Forces the external state of all enabled items in the specified Dialog Box to match their appearance.

It does this by calling the mdlDialog_itemSetState function for each enabled item.

Parameters

[in]

dbP

MSDialog that contains items to attach

Remarks

To insure that the current input focus item (if any) within the dialog contains a valid value, the focus is removed and then restored to that item. This causes the contents of the item to be validated as part of the standard focus out processing.

This function is called automatically when the standard OK push button is activated by the user. Most MDL dialog programmers will never need to call this function.

Returns

SUCCESS, or ERROR if dbP is not a pointer to a Dialog Box, or the current input focus item (if any) within the dialog contains a value that is out of range.

See also

mdlDialog_itemSetState mdlDialog_itemsSynch

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemsAttach	(	MSDialogP	dbP,
		int	nToInsert,
		DialogItem **	diPListPP,
		int	beforeItemIndex,
		bool	drawItems
	)

Attaches dialog items from a DialogItem array into the specified Dialog Box.

Parameters

[in]	dbP	MSDialog to contain items
[in]	nToInsert	the number of items to attach
[in]	diPListPP	pointer to an array of DialogItem pointers to attach
[in]	beforeItemIndex	0-based index of item to load before, or -1 to indicate appending to the end of the MSDialog's item list
[in]	drawItems	indicates whether to draw the items after attaching (true)

Returns

SUCCESS, or Error if dbP is not a pointer to a Dialog Box or the diPListPP is invalid.

See also

mdlDialog_itemsDetach

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemsDetach	(	MSDialogP	dbP,
		int	startItemIndex,
		int	maxItemIndex,
		bool	eraseItems
	)

Detaches dialog items from a MSDialog's item list.

Parameters

[in]	dbP	MSDialog to detach items from
[in]	startItemIndex	0-based index of the first item to detach
[in]	maxItemIndex	0-based index of the last item to detach, or -1 to remove items to the end
[in]	eraseItems	indicates whether to erase the items after detaching (true)

Returns

SUCCESS, or ERROR if dbP is not a pointer to a Dialog Box.

See also

mdlDialog_itemsDetach

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemSetCancel	(	MSDialogP	dbP,
		int	iItem
	)

Sets a new GUI item as the cancel item.

Parameters

[in]	dbP	MSDialog that contains item
[in]	iItem	specifies the index of the item to be the cancel item.

Returns

SUCCESS, or ERROR if dbP is not a pointer to a Dialog Box or iItem is out of range.

See also

mdlDialog_itemSetDefault

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemSetColor	(	MSDialogP	dbP,
		int	iItem,
		int	itemColorType,
		BSIColorDescrP	colorP
	)

Sets a specific color for the item indicated by riP.

Parameters

[in]	dbP	MSDialog that contains item to process
[in]	iItem	specifies the index of the item to set the color in. iItem must be greater than or equal to 0, and less than the number of items in the dialog box. Use mdlDialog_itemsGetNumberOf to determine the number of items in a Dialog Box.
[in]	itemColorType	one of the color types beginning with "DITEM_COLORTYPE_" defined in msdefs.h.
[in]	colorP	a pointer to a BSIColorDescr which will become the new specified color for the item.

Returns

SUCCESS if all parameters are are valid, else ERROR.

See also

mdlDialog_itemGetColor mdlDialog_itemsGetNumberOf

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemSetDefault	(	MSDialogP	dbP,
		int	iItem
	)

Sets a new GUI item as the default action item.

Parameters

[in]	dbP	MSDialog that contains item
[in]	iItem	specifies the index of the item to be the default item.

Returns

SUCCESS, or ERROR if dbP is not a pointer to a Dialog Box or iItem is out of range.

See also

mdlDialog_itemSetCancel

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemSetEnabledState	(	MSDialogP	dbP,
		int	iItem,
		bool	enabled,
		bool	ignoreFocusOutErrors
	)

Sets the enabled state (enabled or disabled) of an item within the specified Dialog Box.

Parameters

[in]	dbP	MSDialog that contains item
[in]	iItem	parameter specifies the index of the item to enable or disable. itemIndex must be greater than or equal to 0, and less than the number of items in the Dialog Box. Use mdlDialog_itemsGetNumberOf to determine the number of items in a Dialog Box.
[in]	enabled	parameter should be set to true to enable the item, or false to disable the item. The user can interact with an enabled item; a disabled item is drawn with dim text (if any) and ignores mouse presses and keyboard events.
[in]	ignoreFocusOutErrors	parameter can be used to ignore any focusing out errors (such as the current value being out of range) that may occur if the item to be disabled has the keyboard focus. It should usually be set false which indicates that focus out errors should not be ignored.

Returns

SUCCESS, or ERROR if db is not a pointer to a Dialog Box, itemIndex is out of range, or the item has the focus and the focus can not be removed (because the current value is out of range).

See also

mdlDialog_itemsGetNumberOf

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemSetExtent	(	MSDialogP	dbP,
		int	iItem,
		SextentCP	sextentP,
		bool	redraw
	)

Sets the extent of an item within the dialog box specified by dbP.

Parameters

[in]	dbP	MSDialog that contains item
[in]	iItem	parameter specifies the index of the item to set the extent of. itemIndex must be greater than or equal to 0, and less than the number of items in the Dialog Box. Use the mdlDialog_itemsGetNumberOf function to determine the number of items in a Dialog Box.
[in]	sextentP	parameter points at a variable that specifies the new location and size of the item. Positive values for the origin.x, origin.y, width or height fields of Sextent indicate that dialog coordinate units are being specified. Negative values should be used to specify the new location or dimension in pixels. In general, pixel coordinates should be avoided since problems may occur if the Dialog Box is moved to a screen that uses a different text font size.
[in]	redraw	if true (as it usually is), the item will be drawn in its new location.

Returns

SUCCESS, or ERROR if either dbP is not a pointer to a Dialog Box, or iItem is out of range.

See also

mdlDialog_itemsGetNumberOf

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemSetLabel	(	MSDialogP	dbP,
		int	iItem,
		WCharCP	pwString
	)

Sets the label of an item within the dialog box specified by dbP.

Parameters

[in]	dbP	MSDialog that contains item
[in]	iItem	parameter specifies the index of the item to set the label of. itemIndex must be greater than or equal to 0 and less than the number of items in the Dialog Box. Use the mdlDialog_itemsGetNumberOf function to determine the number of items in a Dialog Box.
[in]	pwString	Unicode string to be the item's new label.

Returns

SUCCESS, or ERROR if dbP is not a pointer to a Dialog Box, or iItem is out of range.

See also

mdlDialog_itemSetLabelA

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemSetState	(	bool *	stateChangedP,
		MSDialogP	dbP,
		int	iItem
	)

Forces the specified Dialog Box item's external state to match its internal value.

This is the opposite behavior of mdlDialog_itemSynch, which forces the appearance and internal value of an item to match its external state.

Parameters

[out]

stateChangedP

parameter points at an integer variable which is set to true if the item's internal value was different than its external state.

Remarks

If the item has a synonym item list resource attached to it, synchronize messages will be sent to all items in the list.

Parameters

[in]	dbP	parameter specifies a Dialog Box.
[in]	iItem	parameter specifies the index of the item whose external state or internal value the function is setting. itemIndex must be greater than or equal to 0 and less than the number of items in the Dialog Box. Use the mdlDialog_itemsGetNumberOf function to determine the number of items in a Dialog Box.

Returns

SUCCESS, or ERROR if dbP doesn't point to a Dialog Box, or iItem is out of range.

See also

mdlDialog_itemsGetNumberOf mdlDialog_itemSynch mdlDialog_itemSetValue

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemSetStringValue	(	bool *	valueChangedP,
		WCharCP	stringValueP,
		MSDialogP	dbP,
		int	iItem
	)

A helper function to set the internal value of the specified Dialog Box item to a string value.

Parameters

[out]	valueChangedP	parameter points at a bool variable which is set to true if the new value is different than the item's old internal value.
[in]	stringValueP	item's new Unicode string value
[in]	dbP	parameter specifies a Dialog Box.
[in]	iItem	parameter specifies the index of the item whose external state or internal value the function is setting. itemIndex must be greater than or equal to 0 and less than the number of items in the Dialog Box. Use the mdlDialog_itemsGetNumberOf function to determine the number of items in a Dialog Box.

Returns

SUCCESS, or ERROR if dbP doesn't point to a Dialog Box, or iItem is out of range.

See also

mdlDialog_itemSetStringValueA

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemSetValue	(	bool *	valueChangedP,
		MSValueDescrCR	itemValue,
		MSDialogP	dbP,
		int	iItem
	)

Sets the internal value of the specified Dialog Box item to a certain value.

Parameters

[out]	valueChangedP	parameter points at a bool variable which is set to true if the new value is different than the item's old internal value.
[in]	itemValue	item's new value, represented as a MSValueDescr struct.
[in]	dbP	parameter specifies a Dialog Box.
[in]	iItem	parameter specifies the index of the item whose external state or internal value the function is setting. itemIndex must be greater than or equal to 0 and less than the number of items in the Dialog Box. Use the mdlDialog_itemsGetNumberOf function to determine the number of items in a Dialog Box.

Returns

SUCCESS, or ERROR if dbP doesn't point to a Dialog Box, or iItem is out of range.

See also

mdlDialog_itemSetValue mdlDialog_itemSetStringValueA

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemsFree	(	MSDialogP	dbP,
		int	startItemIndex,
		int	maxItemIndex
	)

Frees all the specified dialog items from the specified Dialog Box.

Parameters

[in]	dbP	MSDialog that contains items to free
[in]	startItemIndex	startItmeIndex and maxItemIndex parameters specify the starting and ending indexes of the items to free. startItemIndex and maxItemIndex must be greater than or equal to 0, and less than the number of items in the Dialog Box. Use mdlDialog_itemsGetNumberOf to determine the number of items in a Dialog Box.
[in]	maxItemIndex	see startItemIndex

Returns

SUCCESS, of ERROR if dbP is not a pointer to a Dialog Box.

See also

mdlDialog_itemsGetNumberOf

Remarks

Required Library: mdlbltin.lib

int mdlDialog_itemsGetNumberOf

(

MSDialogP

dbP

)

Retrieves the number of dialog items contained by the specified Dialog Box.

Parameters

[in]

dbP

MSDialog to get number of items

Returns

The number of dialog items contained in the specified Dialog Box. It returns -1 if db does not point to a Dialog box.

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemShow	(	MSDialogP	dbP,
		int	iItem
	)

Shows a previously hidden item within the specified Dialog Box.

Parameters

[in]	dbP	MSDialog that contains item to show
[in]	iItem	specifies the index of the item to show. itemIndex must be greater than or equal to 0, and less than the number of items in the dialog box. Use mdlDialog_itemsGetNumberOf to determine the number of items in a Dialog Box.

Remarks

Whether an item is hidden or not can be determined by looking at the item's DialogItem attributes.hidden bit.

Returns

SUCCESS, or ERROR if dbP is not a pointer to a Dialog Box or iItem is out of range.

See also

mdlDialog_itemHide mdlDialog_itemsGetNumberOf

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemsLoad	(	MSDialogP	dbP,
		DialogItemListRsc *	dilRP,
		RscFileHandle	rFileH,
		MdlDesc *	ownerMD,
		int	beforeItemIndex,
		Point2dP	originP,
		bool	drawItems
	)

Loads the items specified by data pointed at by dilRP into the specified Dialog Box.

Parameters

[in]	dbP	MSDialog in which to load items
[in]	dilRP	parameter points to a DialogItemListRsc structure that specifies the items to load. A DialogItemListRsc structure (defined in dlogbox.r.h) contains the number of items to load and an array of DialogItemRsc structures. The fields of the DialogItemRsc structures should be set just as if a definition in a resource file was being created.
[in]	rFileH	parameter specifies the resource file to search for the dialog box item resources. If NULL, all the calling application's open resource files, then MicroStation's open resource files will be searched.
[in]	ownerMD	parameter should be set to NULL.
[in]	beforeItemIndex	parameter specifies the index of the item before which the new items will be loaded. Specify -1 to indicate that the items should be appended at the end of the dialog item list.
[in]	originP	parameter is used to specify the origin of a temporary coordinate system that will be used when loading the dialog items. The units of the point pointed at by originP should be in dialog coordinate units. The extent field of the DialogItemRsc structures contained by the structure pointed at by dilRP will be interpreted with an origin at originP. Specify NULL for originP to indicate the origin should be at (0, 0), the upper left corner of the Dialog Box.
[in]	drawItems	if parameter is true, the items will be drawn after they are loaded.

Returns

SUCCESS, or ERROR if dbP is not a pointer to a Dialog Box, or one of item resources could not be found.

See also

mdlDialog_itemLoad

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemsObscure	(	MSDialogP	dbP,
		int	iStartItem,
		int	iEndItem,
		bool	doObscure
	)

Obscures (hides) or unobscures items on the dialog specified by dbP and sets/unsets the attributes.obscured flag.

Parameters

[in]	dbP	dialog to process
[in]	iStartItem	0-based index of the starting item to obscure/unobscure
[in]	iEndItem	0-based index of the ending item to obscure/unobscure
[in]	doObscure	indicates whether to obscure (true) or unobscure the items

Returns

SUCCESS, or ERROR if dbP is not a pointer to a Dialog Box.

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemsSwapOrder	(	MSDialogP	dbP,
		int	itemIndex1,
		int	itemIndex2
	)

Swaps the positions of two dialog items in a Dialog Box.

This does not affect their display coordinates within the Dialog Box.

Parameters

[in]	dbP	points to the Dialog Box that contains the items.
[in]	itemIndex1	identifies the items to be swapped
[in]	itemIndex2	identifies the items to be swapped

Returns

SUCCESS if the items could be swapped.

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemsSynch

(

MSDialogP

dbP

)

Forces the appearance of all items in the Dialog Box specified by dbP to match their external state.

It does this by calling mdlDialog_itemSynch for each visible item.

Parameters

[in]

dbP

dialog to synch

Returns

SUCCESS, or ERROR if dbP is not a pointer to a Dialog Box.

See also

mdlDialog_itemSynch mdlDialog_itemsApply

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemSynch	(	MSDialogP	dbP,
		int	iItem
	)

Forces the appearance of an item to match its external state.

This is the opposite behavior of mdlDialog_itemSetState, which forces the external state of an item to match its appearance.

Parameters

[in]	dbP	parameter specifies a Dialog Box.
[in]	iItem	parameter specifies the index of the item to synchronize. itemIndex must be greater than or equal to 0, and less than the number of items in the Dialog Box. Use the mdlDialog_itemsGetNumberOf function to determine the number of items in a Dialog Box.

Remarks

Be careful when using mdlDialog_itemSynch from the DIALOG_MESSAGE_SYNCH case of a Dialog Box hook. If you do not take any special precautions this will result in a recursive infinite loop and corrupt your stack.

Returns

SUCCESS, or ERROR if dbP is not a pointer to a Dialog Box, or iItem is out of range.

See also

mdlDialog_itemSetState mdlDialog_itemsGetNumberOf

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemSynchByTypeAndId	(	MSDialogP	dbP,
		RscType	itemType,
		RscId	itemId
	)

Causes a DITEM_MESSAGE_SYNCHRONIZE message to be sent to the dialog item indicated by itemType and itemId in the Dialog Box indicated by dbP.

Parameters

[in]	dbP	points to the Dialog Box containing the item to be synched.
[in]	itemType	indicates the type or resource class of the item.
[in]	itemId	is the resource ID of the item.

Returns

SUCCESS if the item could be found and a synch message could be sent to it, or ERROR.

Remarks

Required Library: mdlbltin.lib

StatusInt mdlDialog_itemSynchOthers

(

RawItemHdrP

riP

)

Causes a DITEM_MESSAGE_SYNCHRONIZE message to be sent to all items listed in the synonym list indicated for the item indicated by riP.

All dialogs are processed.

Parameters

[in]

riP

The item whose synonym list will be processed.

Returns

SUCCESS if the item and its dialog are valid, else ERROR.

Remarks

Required Library: mdlbltin.lib