Modules | Functions
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...
 
DialogItemmdlDialog_itemGetByIndex (MSDialogP dbP, int itemIndex)
 Retrieves a pointer to the requested dialog item contained in the specified Dialog Box. More...
 
DialogItemmdlDialog_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...
 
DialogItemmdlDialog_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...
 
DialogItemmdlDialog_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...
 
DialogItemmdlDialog_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]dbPMSDialog that contains item to find
[in]ptPpointer to a Point2d containing the local coordinates of the item to find
[in]ignoreEnabledStatusindicates 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]dbPMSDialog 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]dbPMSDialog we're setting
[in]iItemparameter 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]ignoreFocusOutErrorsparameter 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]dbPMSDialog that contains the item to draw
[in]iItemspecifies 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]dbPMSDialog that contains the item to draw
[in]iItemitem index of the item to draw
[in]eraseFirstindicates 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]dbPMSDialog that contains the item
[in]itemIndexparameter 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;
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]dbPMSDialog that contains item
[in]typetype of item to get
[in]idparameter specifies the resource id of the item to retrieve a pointer to.
[in]startingIndexparameter 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;
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]dbPMSDialog that contains item
[in]typetype of item to get
[in]idparameter specifies the resource id of the item to retrieve a pointer to.
[in]ownerMDowner of item, NULL means owner of parent
[in]startingIndexparameter 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]searchChildrenparameter 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]dbPMSDialog that contains item
[in]typetype of the item to get
[in]indexindex 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]dbPMSDialog that contains item to process
[in]iItemspecifies 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]itemColorTypeone 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]itemValuespecifies the MSValueDescr to receive the value. The MSValueDescr struct provides methods to query the type of data and methods to get the data.
[in]dbPparameter specifies a Dialog Box.
[in]iItemparameter 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]valueStringspecifies the WString to receive the value.
[in]dbPparameter specifies a Dialog Box.
[in]iItemparameter 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]itemValuespecifies the MSValueDescr to receive the value. The MSValueDescr struct provides methods to query the type of data and methods to get the data.
[in]dbPparameter specifies a Dialog Box.
[in]iItemparameter 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]dbPMSDialog that contains item to hide
[in]iItemspecifies 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]ignoreFocusOutErrorsparameter 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]dbPMSDialog to contain item
[in]diRPparameter 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]rFileHparameter 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]ownerMDparameter should be set to NULL.
[in]beforeItemIndexparameter 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]originPparameter 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]dbPMSDialog that contains item to move
[in]iItemspecifies 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]ptPparameter 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]redrawif 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]dbPis the dialog that contains the item to reload.
[in]iItemis the index of the item to reload.
[in]redrawindicates 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]dbPdialog to process
[in]pNewContentrectangle representing the new content rectangle of the dialog in local coordinates
[in]pOldContentrectangle representing the old content rectangle of the dialog in local coordinates
[in]pSashItemSash item pointer.
[in]pTopLeftItemitem pointer of the item on top of, or to the left of, the Sash item.
[in]bTopLeftEraseindicates whether to erase the item before adjusting it.
[in]bTopLeftFullRedrawindicates whether to draw the entire item or only the part of the item that changed.
[in]pBottomRightItemitem pointer of the item on bottom of, or to the right of, the Sash item.
[in]bBottomRightEraseindicates whether to erase the item before adjusting it.
[in]bBottomRightFullRedrawindicates 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]dbPdialog to process
[in]pNewContentrectangle representing the new content rectangle of the dialog in local coordinates
[in]pOldContentrectangle representing the old content rectangle of the dialog in local coordinates
[in]pSashItemAdjustItem parameters for the Sash item.
[in]pTopLeftItemAdjustItem parameters for item on top of, or to the left of, the Sash item.
[in]pBottomRightItemAdjustItem 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;
};
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]dbPMSDialog 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]dbPMSDialog to contain items
[in]nToInsertthe number of items to attach
[in]diPListPPpointer to an array of DialogItem pointers to attach
[in]beforeItemIndex0-based index of item to load before, or -1 to indicate appending to the end of the MSDialog's item list
[in]drawItemsindicates 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]dbPMSDialog to detach items from
[in]startItemIndex0-based index of the first item to detach
[in]maxItemIndex0-based index of the last item to detach, or -1 to remove items to the end
[in]eraseItemsindicates 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]dbPMSDialog that contains item
[in]iItemspecifies 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]dbPMSDialog that contains item to process
[in]iItemspecifies 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]itemColorTypeone of the color types beginning with "DITEM_COLORTYPE_" defined in msdefs.h.
[in]colorPa 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]dbPMSDialog that contains item
[in]iItemspecifies 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]dbPMSDialog that contains item
[in]iItemparameter 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]enabledparameter 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]ignoreFocusOutErrorsparameter 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]dbPMSDialog that contains item
[in]iItemparameter 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]sextentPparameter 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]redrawif 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]dbPMSDialog that contains item
[in]iItemparameter 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]pwStringUnicode 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]stateChangedPparameter 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]dbPparameter specifies a Dialog Box.
[in]iItemparameter 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]valueChangedPparameter points at a bool variable which is set to true if the new value is different than the item's old internal value.
[in]stringValuePitem's new Unicode string value
[in]dbPparameter specifies a Dialog Box.
[in]iItemparameter 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]valueChangedPparameter points at a bool variable which is set to true if the new value is different than the item's old internal value.
[in]itemValueitem's new value, represented as a MSValueDescr struct.
[in]dbPparameter specifies a Dialog Box.
[in]iItemparameter 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]dbPMSDialog that contains items to free
[in]startItemIndexstartItmeIndex 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]maxItemIndexsee 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]dbPMSDialog 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]dbPMSDialog that contains item to show
[in]iItemspecifies 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]dbPMSDialog in which to load items
[in]dilRPparameter 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]rFileHparameter 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]ownerMDparameter should be set to NULL.
[in]beforeItemIndexparameter 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]originPparameter 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]drawItemsif 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]dbPdialog to process
[in]iStartItem0-based index of the starting item to obscure/unobscure
[in]iEndItem0-based index of the ending item to obscure/unobscure
[in]doObscureindicates 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]dbPpoints to the Dialog Box that contains the items.
[in]itemIndex1identifies the items to be swapped
[in]itemIndex2identifies 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]dbPdialog 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]dbPparameter specifies a Dialog Box.
[in]iItemparameter 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]dbPpoints to the Dialog Box containing the item to be synched.
[in]itemTypeindicates the type or resource class of the item.
[in]itemIdis 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]riPThe item whose synonym list will be processed.
Returns
SUCCESS if the item and its dialog are valid, else ERROR.
Remarks
Required Library: mdlbltin.lib

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