Public Member Functions | List of all members
ListBox Struct Reference

ListBox represents a ListBox dialog item in a MicroStation / PowerPlatform dialog box. More...

#include <ListBox.h>

Inheritance diagram for ListBox:
DialogItem

Public Member Functions

StatusInt DrawContents (int relRowIndex, int relColIndex)
 Draws the contents of the ListBox item. More...
 
StatusInt EnableCells (int minRowIndex, int maxRowIndex, int minColIndex, int maxColIndex, bool enable, bool redraw=true)
 Enables or disables a range of cells in the ListBox. More...
 
StatusInt FindCell (int *iRowP, int *iColP, Point2dP ptP)
 Returns the row and column in the ListBox at the current mouse position, ptP. More...
 
StatusInt GetDisplayRange (int *topRowIndexP, int *bottomRowIndexP, int *leftColIndexP, int *rightColIndexP)
 Gets the range of the cells that are displayed in the ListBox. More...
 
StatusInt GetNextSelection (bool *foundP, int *rowIndexP, int *colIndexP)
 Searches for the next selected cell of the ListBox. More...
 
StatusInt GetSelectRange (int *minRowIndexP, int *maxRowIndexP, int *minColIndexP, int *maxColIndexP)
 Gets the range of the cells that are currently selected in the ListBox. More...
 
UInt32 GetAttributes ()
 Retrieves the attributes for the ListBox. More...
 
UInt32 GetExtendedAttributes ()
 Retrieves the extended attributes for the ListBox. More...
 
ListModel * GetListModel ()
 Retrieves a pointer to the ListModel that is serving as the data model for the ListBox. More...
 
int GetNumberOfColumns ()
 Retrieves the number of columns specified for the ListBox. More...
 
int GetNumberOfDisplayRows ()
 Retrieves the number of rows displayed for the ListBox. More...
 
UInt32 GetSizeNumColumn ()
 Retrieves the maximum number of digits necessary to number the rows. More...
 
UInt32 GetStatusFlags ()
 Retrieves the status flags for the ListBox. More...
 
StringListP GetStringList ()
 Retrieves a pointer to the StringList that is serving as the data model for the ListBox. More...
 
bool IsCellEnabled (int rowIndex, int colIndex)
 Determines if a cell in the ListBox is enabled. More...
 
bool IsCellSelected (int rowIndex, int colIndex)
 Determines if a cell in the ListBox is selected. More...
 
StatusInt RowsChanged (bool redraw=true)
 Informs the ListBox item that the number of rows in its StringList or ListModel has changed. More...
 
StatusInt SelectCells (int minRowIndex, int maxRowIndex, int minColIndex, int maxColIndex, bool selectOn, bool redraw=true)
 Selects a range of cells in the ListBox. More...
 
StatusInt SetAttributes (UInt32 attributes, bool redraw=true)
 Sets the attributes for the ListBox. More...
 
StatusInt SetExtendedAttributes (UInt32 attributes, bool redraw=true)
 Sets the extended attributes for the ListBox. More...
 
StatusInt SetListModel (ListModel *pListModel, bool redraw=true)
 Sets the ListModel for the ListBox. More...
 
StatusInt SetDisplayRowCount (int value, bool redraw=true)
 Sets the number of display rows. More...
 
StatusInt SetSizeNumColumn (UInt32 value, bool redraw=true)
 Sets the maximum number of digits necessary to number the rows. More...
 
StatusInt SetSortBeginRow (int sortBeginRow)
 Sets the row from which to start user sorting. More...
 
StatusInt SetStringList (StringListP strListP, int nColumns)
 Sets the StringList for the ListBox. More...
 
StatusInt SetTopRow (int topRowIndex, bool redraw=true)
 Sets the index of the top row displayed. More...
 
- Public Member Functions inherited from DialogItem
DialogItemAttributes const & GetAttributes () const
 Returns a reference to the DialogItemAttributes for this DialogItem. More...
 
RscId GetId () const
 Returns the id of this DialogItem. More...
 
int GetItemIndex () const
 Returns the index within the MSDialog of this DialogItem. More...
 
MSDialogP GetDialog () const
 Returns a pointer to the MSDialog that is hosting this DialogItem. More...
 
RawItemHdrP GetRawItem () const
 Returns a pointer to the RawItemHdr associated with this DialogItem. More...
 
BSIRect const & GetRect () const
 Returns a reference to the rectangle for this DialogItem. This rectangle is used for mouse processing. More...
 
RscType GetType () const
 Returns the resource type of this DialogItem. More...
 
bool HasFocus () const
 Determines if an item has focus. More...
 
bool IsEnabled () const
 Determines if an item is enabled. More...
 
bool IsFocusable ()
 Determines if an item is focusable. More...
 
bool IsDisplayable ()
 Determines if an item can be displayed. More...
 
bool IsHidden ()
 Determines if an item is hidden. More...
 
StatusInt Draw (bool eraseFirst=true)
 Redraws an item within the Dialog Box. More...
 
BSIColorDescr const * GetColor (ItemColorType colorType)
 Gets a specific color for the item. More...
 
StatusInt GetLabel (WStringR label)
 Retrieves the text displayed in the label for this item as a WString. More...
 
int GetLabelLength ()
 Retrieves the length in characters of the label for this item. More...
 
int GetLabelWidth (int fontIndex)
 Retrieves the width in pixels of the label for this item. More...
 
GuiLayoutControlP GetLayoutControl ()
 Retrieves the GuiLayoutControl for this item. More...
 
GuiLayoutPropertiesP GetLayoutProperties ()
 Retrieves the GuiLayoutProperties for this item. More...
 
DialogItemP GetNext (bool includeLayoutItems=false)
 Retrieves the next item in the dialog item list. More...
 
DialogItemP GetNextVisible (bool inclusive=false)
 Retrieves the next visible item in the dialog item list. More...
 
DialogItemP GetOwnerItem ()
 Retrieves the DialogItem pointer of the owning dialog item, if any. More...
 
StatusInt GetPopupMenuText (WStringR text)
 Retrieves the text displayed in the Show/Hide PopupMenu. More...
 
DialogItemP GetPrev (bool includeLayoutItems=false)
 Retrieves the previous item in the dialog item list. More...
 
StatusInt GetState (MSValueDescrR state)
 Retrieves this item's external state. This is the value of the application data that the item controls,. More...
 
StatusInt GetValue (MSValueDescrR value)
 Retrieves this item's internal value. This is the value that is used to determine the item's. More...
 
StatusInt GetValue (WStringR value)
 Retrieves the item's internal value as a string. This is the value that is used to determine the item's. More...
 
StatusInt Hide (bool ignoreFocusOutErrors=false)
 Hides an item within the Dialog Box. More...
 
StatusInt Move (Point2dP newPtP, bool redraw=true)
 Moves an item within the Dialog Box. More...
 
StatusInt Obscure ()
 Obscures the item. Unobscure() reverses this process. More...
 
StatusInt PopupClose (bool update)
 Notifies the owner item to close its popup window. More...
 
StatusInt PopupOpen (bool bGrabMouse, Point2dP pPopupPt, MSDialogP *popupDbPP)
 Opens a Popup dialog associated with this item. If the popup should have focus and the mouse then. More...
 
StatusInt ReloadData (bool redraw=true)
 Reloads the item information for this item. More...
 
StatusInt SetBalloonText (WCharCP text, bool bSetPopupText=true)
 Sets the information displayed in the balloon window for this item. More...
 
StatusInt SetColor (ItemColorType colorType, BSIColorDescr *colorP)
 Sets a specific color for the item. More...
 
StatusInt SetDisabledBalloonText (WCharCP text)
 Sets the text to be displayed in the balloon window when this item is disabled. More...
 
StatusInt SetEnabled (bool enabled, bool ignoreFocusOutErrors=false)
 Sets the enabled state (enabled or disabled) of a dialog item. More...
 
StatusInt SetExtent (SextentCP sextent, bool redraw=true)
 Sets the extent (position and size) of an item within the dialog. More...
 
StatusInt SetFlyoverText (WCharCP text)
 Sets the information displayed in the flyover field in the Status Bar for this item. More...
 
StatusInt SetLabel (WCharCP pwString)
 Sets the label of an item. More...
 
StatusInt SetLabelFont (int fontIndex)
 Sets the font used for the label of this item. More...
 
StatusInt SetPopupMenuText (WCharCP text)
 Sets the text displayed in the Show/Hide PopupMenu. More...
 
StatusInt SetState (bool *stateChangedP, bool synchOthers=true)
 Forces the specified item's external state to match its internal value. More...
 
StatusInt SetValue (bool *valueChangedP, MSValueDescrCR newValue)
 Sets the internal value of the specified item to a certain value. More...
 
StatusInt SetValue (bool *valueChangedP, WCharCP newValue)
 Sets the internal value of the specified item to a certain string value. More...
 
StatusInt Show ()
 Shows a previously hidden item. More...
 
StatusInt Synchronize ()
 Forces the appearance of an item to match its external state. This is the opposite. More...
 
StatusInt SynchronizeOthers ()
 Causes a DITEM_MESSAGE_SYNCHRONIZE message to be sent to all items listed in the. More...
 
StatusInt Unobscure ()
 Unobscures the item. The Obscure method obscures the item. More...
 
template<typename T >
GetTypePtr (RscType itemType)
 
 DialogItem ()
 Constructs a DialogItem object. More...
 
 ~DialogItem ()
 Destructs a DialogItem object. More...
 

Additional Inherited Members

- Public Attributes inherited from DialogItem
RscType type
 type of item, ie. RTYPE_PushButton More...
 
RscId id
 id of item More...
 
int itemIndex
 index within parent More...
 
UInt64 itemArg
 item arg More...
 
BSIRect rect
 mouse sensitive/update region of item More...
 
Sextent extent
 Position / size (in dcoord units) More...
 
Point2d origin
 Position (in dcoord units) More...
 
DialogItemAttributes attributes
 Attributes from the resource. More...
 
RawItemHdrrawItemP
 RawItemHdr associated with this DialogItem. More...
 
DialogItemparentDiP
 Parent DialogItem. More...
 

Detailed Description

ListBox represents a ListBox dialog item in a MicroStation / PowerPlatform dialog box.

In order to use the ListBox struct, you must first get a ListBoxP pointer from a DialogItem using the GetTypePtr or GetItemPtrByTypeAndId template functions. For example:

ListBoxP pListBox = GetDialogItem ()->GetTypePtr <ListBoxP> (RTYPE_ListBox);

Member Function Documentation

StatusInt DrawContents ( int  relRowIndex,
int  relColIndex 
)

Draws the contents of the ListBox item.

Parameters
[in]relRowIndexspecifies the relative row index (0 based) of the row to draw.Relative row 0 indicates that whatever is contained in the first row should be drawn, not that the first row of the ListBox's StringList should be drawn. If relRowIndex is -1, all the displayed rows in the ListBox will be redrawn.
[in]relColIndexspecifies the relative column index (0 based) of the column to draw.Relative column 0 indicates that the first column in the ListBox should be drawn.If relColIndex is - 1, all the displayed columns in the ListBox will be redrawn.
Remarks
The entire ListBox contents is redrawn if -1 is specified for both relRowIndex and relColIndex.
Returns
SUCCESS, or non-zero value if an error occurred.
Remarks
Required Library : mdlbltin.lib
StatusInt EnableCells ( int  minRowIndex,
int  maxRowIndex,
int  minColIndex,
int  maxColIndex,
bool  enable,
bool  redraw = true 
)

Enables or disables a range of cells in the ListBox.

The enable parameter should be set to true to enable the range of cells, or false to disable the cells.An enabled cell is selectable; a disabled cell is dim and unselectable.

Remarks
The minRowIndex, maxRowIndex, minColIndex, and maxColIndex parameters together specify the range of cells to affect. Row and column indexes start with 0.
Parameters
[in]minRowIndexmin row of area to enable
[in]maxRowIndexmax row of area to enable
[in]minColIndexmin col of area to enable
[in]maxColIndexmax col of area to enable
[in]enablefalse = cells disabled (dim, unselectable)
[in]redrawtrue specifies that the affected cells should be redrawn if they are currently visible inside of the ListBox.
Returns
SUCCESS, or non-zero value if an error occurred.
Remarks
Required Library : mdlbltin.lib
StatusInt FindCell ( int *  iRowP,
int *  iColP,
Point2dP  ptP 
)

Returns the row and column in the ListBox at the current mouse position, ptP.

Parameters
[out]iRowPThe row in the ListBox found at the cursor position.Can be NULL
[out]iColPThe column in the ListBox found at the cursor position.Can be NULL
[in]ptPthe cursor location
Returns
SUCCESS if a row and colunm were located at the cursor position, or a non-zero value otherwise.
Remarks
Required Library : mdlbltin.lib
UInt32 GetAttributes ( )

Retrieves the attributes for the ListBox.

Returns
The ListBox attributes. The bits that can be set in the return value include LISTATTR_LABELONSIDE, LISTATTR_RANGESELECTION, and so on. The constants are defined in dlogbox.r.h.
Remarks
Required Library : mdlbltin.lib
StatusInt GetDisplayRange ( int *  topRowIndexP,
int *  bottomRowIndexP,
int *  leftColIndexP,
int *  rightColIndexP 
)

Gets the range of the cells that are displayed in the ListBox.

The function is used to determine what part of the ListBox's StringList or ListModel is currently being displayed. The first and last displayed rows in the ListBox are copied to the locations specified by topRowIndexP and bottomRowIndexP. The first and last displayed columns in the ListBox are copied to the locations specified by leftColIndexP and rightColIndexP. topRowIndexP, bottomRowIndexP, leftColIndexP or rightColIndexP can be NULL, indicating that the caller doesn't need the value.

Parameters
[out]topRowIndexProw # of 1st row displayed (0 based)
[out]bottomRowIndexProw # of last row displayed (0 based)
[out]leftColIndexPcol # of leftmost col displayed (0 based)
[out]rightColIndexPcol # of rightmost col displayed (0 based)
Remarks
For example, suppose that a ListBox is configured to display five rows at a time with one column, and that its StringList contains twenty members. If the first row of the ListBox is displaying the sixth member of the StringList (whose row index is five), the integers pointed at by topRowIndexP, bottomRowIndexP, leftColIndexP and rightColIndexP will be set to 5, 9, 0 and 0 respectively.
Row and column indexes start with 0.
Returns
SUCCESS, or non - zero value if an error occurred.This usually means that listBoxP is not a pointer to a ListBox item.
Remarks
Required Library : mdlbltin.lib
UInt32 GetExtendedAttributes ( )

Retrieves the extended attributes for the ListBox.

Returns
The ListBox extended attributes. The bits that can be set in the return value include LISTATTRX_FOCUSOUTLOOK, LISTATTRX_HEIGHTFORICONS, and so on. The constants are defined in dlogbox.r.h.
Remarks
Required Library : mdlbltin.lib
ListModel* GetListModel ( )

Retrieves a pointer to the ListModel that is serving as the data model for the ListBox.

Either a ListModel or a StringList is the data model for a ListBox.

Returns
a pointer to the ListModel
Remarks
Required Library : mdlbltin.lib
StatusInt GetNextSelection ( bool *  foundP,
int *  rowIndexP,
int *  colIndexP 
)

Searches for the next selected cell of the ListBox.

Parameters
[out]foundPThe boolean variable pointed at by foundP is set to true if a selected cell was found.
[in,out]rowIndexPInput is the row of the cell to start search after. Output is row index of next selected cell.
[in,out]colIndexPInput is the column of the cell to start search after. Output is column index of next selected cell.
Remarks
On input rowIndexP and colIndexP specify the cell to start the search after. Pointing at -1 with both of these parameters indicates that the search should start from the beginning of the list.
If a selected cell is found, its row index and column index are copied to the locations specified by rowIndexP and colIndexP.
Returns
SUCCESS, or non-zero value if an error occurred.
Remarks
Required Library : mdlbltin.lib
int GetNumberOfColumns ( )

Retrieves the number of columns specified for the ListBox.

Returns
the number of columns
Remarks
Required Library : mdlbltin.lib
int GetNumberOfDisplayRows ( )

Retrieves the number of rows displayed for the ListBox.

Returns
the number of rows displayed
Remarks
Required Library : mdlbltin.lib
StatusInt GetSelectRange ( int *  minRowIndexP,
int *  maxRowIndexP,
int *  minColIndexP,
int *  maxColIndexP 
)

Gets the range of the cells that are currently selected in the ListBox.

The first and last selected rows in the ListBox are copied to the locations specified by the minRowIndexP and maxRowIndexP parameters.The first and last selected columns in the ListBox are copied to the locations specified by the minColIndexP and maxColIndexP parameters.Any of the parameters minRowIndexP, maxRowIndexP, minColIndexP or maxColIndexP can be NULL, which indicates that the caller doesn't need the value. Row and column indexes start with 0.

Parameters
[out]minRowIndexPmin row of selection
[out]maxRowIndexPmax row of selection
[out]minColIndexPmin column of selection
[out]maxColIndexPmax column of selection
Remarks
If the ListBox is set up to allow disjoint selections, not all of the cells in the returned range will necessarily be selected.This function only returns the bounds of the selected cells. Use IsCellSelected to determine if a cell in the range is actually selected when disjoint selections are allowed.
Returns
SUCCESS, or non-zero value if an error occurred.
Remarks
Required Library : mdlbltin.lib
UInt32 GetSizeNumColumn ( )

Retrieves the maximum number of digits necessary to number the rows.

Returns
the maximum number of digits necessary for row numbering
Remarks
Required Library : mdlbltin.lib
UInt32 GetStatusFlags ( )

Retrieves the status flags for the ListBox.

Valid values are DISTATUS_NEEDVERTSCROLLBAR and/or DISTATUS_NEEDHORIZSCROLLBAR.

Returns
the status flags for the ListBox
Remarks
Required Library : mdlbltin.lib
StringListP GetStringList ( )

Retrieves a pointer to the StringList that is serving as the data model for the ListBox.

Either a ListModel or a StringList is the data model for a ListBox.

Returns
a pointer to the StringList
Remarks
Required Library : mdlbltin.lib
bool IsCellEnabled ( int  rowIndex,
int  colIndex 
)

Determines if a cell in the ListBox is enabled.

An enabled cell is selectable; a disabled cell is dim and unselectable.

Parameters
[in]rowIndexrow index of cell to test
[in]colIndexcolumn index of cell to test
Remarks
The rowIndex and colIndex parameters indicate which cell to test. Row and column indexes start with 0.
Returns
true if the cell is enabled.
Remarks
Required Library : mdlbltin.lib
bool IsCellSelected ( int  rowIndex,
int  colIndex 
)

Determines if a cell in the ListBox is selected.

Parameters
[in]rowIndexrow index of cell to test
[in]colIndexcolumn index of cell to test
Remarks
The rowIndex and colIndex parameters indicate which cell to test. Row and column indexes start with 0.
Returns
true if the cell is selected.
Remarks
Required Library : mdlbltin.lib
StatusInt RowsChanged ( bool  redraw = true)

Informs the ListBox item that the number of rows in its StringList or ListModel has changed.

An application should call this method whenever the number of rows or members in the ListBox's StringList or ListModel changes. This method corrects the size of the ListBox's Scroll Bar.

Parameters
[in]redrawIf true the ListBox will redraw after internal calculations have been made; if false it will not redraw. This defaults to true.
Returns
SUCCESS, or non-zero value if an error occurs.
Remarks
Required Library : mdlbltin.lib
StatusInt SelectCells ( int  minRowIndex,
int  maxRowIndex,
int  minColIndex,
int  maxColIndex,
bool  selectOn,
bool  redraw = true 
)

Selects a range of cells in the ListBox.

The selectOn parameter should be set to true to select the range of cells, or false to deselect the cells. Selected cells are displayed with a black background color.

Remarks
The minRowIndex, maxRowIndex, minColIndex, and maxColIndex parameters together specify the range of cells to affect. Row and column indexes start with 0.
Parameters
[in]minRowIndexmin row of area to select
[in]maxRowIndexmax row of area to select
[in]minColIndexmin column of area to select
[in]maxColIndexmax column of area to select
[in]selectOnfalse means selection is turned off
[in]redrawWhen true, specifies that the affected cells should be redrawn if they are currently visible inside of the ListBox. This defaults to true.
Returns
SUCCESS, or non-zero value if an error occurred.
Remarks
Required Library : mdlbltin.lib
StatusInt SetAttributes ( UInt32  attributes,
bool  redraw = true 
)

Sets the attributes for the ListBox.

Parameters
[in]attributesThe ListBox attributes. The bits that can be set include LISTATTR_LABELONSIDE, LISTATTR_RANGESELECTION, and so on. The constants are defined in dlogbox.r.h.
[in]redrawWhen true, specifies that the ListBox should be redrawn. This defaults to true.
Returns
SUCCESS, or non-zero value if an error occurred.
Remarks
Required Library : mdlbltin.lib
StatusInt SetDisplayRowCount ( int  value,
bool  redraw = true 
)

Sets the number of display rows.

Parameters
[in]valueThe number of display rows
[in]redrawWhen true, specifies that the ListBox should be redrawn. This defaults to true.
Returns
SUCCESS, or non-zero value if an error occurred.
Remarks
Required Library : mdlbltin.lib
StatusInt SetExtendedAttributes ( UInt32  attributes,
bool  redraw = true 
)

Sets the extended attributes for the ListBox.

Parameters
[in]attributesThe ListBox extended attributes. The bits that can be set include LISTATTRX_FOCUSOUTLOOK, LISTATTRX_HEIGHTFORICONS, and so on. The constants are defined in dlogbox.r.h.
[in]redrawWhen true, specifies that the ListBox should be redrawn. This defaults to true.
Returns
SUCCESS, or non-zero value if an error occurred.
Remarks
Required Library : mdlbltin.lib
StatusInt SetListModel ( ListModel *  pListModel,
bool  redraw = true 
)

Sets the ListModel for the ListBox.

Either a ListModel or a StringList is the data model for a ListBox.

Parameters
[in]pListModelThe ListModel
[in]redrawWhen true, specifies that the ListBox should be redrawn. This defaults to true.
Returns
SUCCESS, or non-zero value if an error occurred.
Remarks
Required Library : mdlbltin.lib
StatusInt SetSizeNumColumn ( UInt32  value,
bool  redraw = true 
)

Sets the maximum number of digits necessary to number the rows.

Parameters
[in]valueThe maximum number of digits necessary to number the rows
[in]redrawWhen true, specifies that the ListBox should be redrawn. This defaults to true.
Returns
SUCCESS, or non-zero value if an error occurred.
Remarks
Required Library : mdlbltin.lib
StatusInt SetSortBeginRow ( int  sortBeginRow)

Sets the row from which to start user sorting.

Parameters
[in]sortBeginRowIndex of the row from which to start user sorting.
Returns
SUCCESS, or non-zero value if an error occurs.
Remarks
Required Library : mdlbltin.lib
StatusInt SetStringList ( StringListP  strListP,
int  nColumns 
)

Sets the StringList for the ListBox.

Either a ListModel or a StringList is the data model for a ListBox.

Parameters
[in]strListPThe StringList
[in]nColumnsThe number of columns of data in the StringList.
Returns
SUCCESS, or non-zero value if an error occurred.
Remarks
Required Library : mdlbltin.lib
StatusInt SetTopRow ( int  topRowIndex,
bool  redraw = true 
)

Sets the index of the top row displayed.

Parameters
[in]topRowIndexindex of the top row displayed
[in]redrawWhen true, specifies that the ListBox should be redrawn. This defaults to true.
Returns
SUCCESS, or non-zero value if an error occurred.
Remarks
Required Library : mdlbltin.lib

The documentation for this struct was generated from the following file:

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