Methods of the ListControl Class

The following sections describe the individual methods.

ReplaceStyle

                                               +-------------------+
                                               V                   |
>>-aListControl~ReplaceStyle(--oldStyle--,--"----+-ICON----------+-+--"--)-><
                                                 +-SMALLICON-----+
                                                 +-LIST----------+
                                                 +-REPORT--------+
                                                 +-ALIGNLEFT-----+
                                                 +-ALIGNTOP------+
                                                 +-AUTOARRANGE---+
                                                 +-ASCENDING-----+
                                                 +-DESCENDING----+
                                                 +-EDIT----------+
                                                 +-HSCROLL-------+
                                                 +-VSCROLL-------+
                                                 +-NOSCROLL------+
                                                 +-NOHEADER------+
                                                 +-NOSORTHEADER--+
                                                 +-NOWRAP--------+
                                                 +-SINGLESEL-----+
                                                 +-SHOWSELALWAYS-+
                                                 +-SHAREIMAGES---+
                                                 +-GROUP---------+
                                                 +-HIDDEN--------+
                                                 +-NOTAB---------+
                                                 +-NOBORDER------+


The ReplaceStyle method removes a window style of a list view control and sets new styles.

Arguments:

The arguments are:

oldStyle

The window style to be removed.

newStyle

The new window styles to be set, which is one or more of the styles listed in the syntax diagram, separated by blanks. For an explanation of the different styles, refer to AddListControl.

Return value:

0 if this method fails.

Example:

The following example comes from a program where the user can switch between the different view styles in a list-view. The list-view is assigned an image list for both the small and normal icons. Radio buttons for the different views are connected to methods. When the user clicks one of the radio buttons, the method for that radio button uses replaceStyle() to remove all of the other view styles and add the specified style.


::method initDialog
  expose list

  self~getRadioControl(IDC_RB_ICON)~check
  self~connectButtonNotify(IDC_RB_REPORT, "CLICKED", onReport)
  self~connectButtonNotify(IDC_RB_LIST, "CLICKED", onList)
  self~connectButtonNotify(IDC_RB_ICON, "CLICKED", onIcon)
  self~connectButtonNotify(IDC_RB_SMALL_ICON, "CLICKED", onSmallIcon)

  list  = self~getListControl(IDC_LV_VIEWS)

  flags = .Image~toID(ILC_COLOR24)
  imageList = .ImageList~create(.Size~new(16), flags, 7, 0)

  imageList~add(.Image~getImage("iconList_16.bmp"))
  list~setImageList(imageList, .Image~toID(LVSIL_SMALL))

  imageList = .ImageList~create(.Size~new(32), flags, 7, 0)

  imageList~add(.Image~getImage("iconList_32.bmp"))
  list~setImageList(imageList, .Image~toID(LVSIL_NORMAL))

  self~populateList(list)

::method onReport
  expose list
  list~replaceStyle("LIST ICON SMALLICON", "REPORT")

::method onList
  expose list
  list~replaceStyle("REPORT ICON SMALLICON", "LIST")

::method onIcon
  expose list
  list~replaceStyle("LIST REPORT SMALLICON", "ICON")

::method onSmallIcon
  expose list
  list~replaceStyle("LIST ICON REPORT", "SMALLICON")

::method populateList private
  use strict arg list

  list~InsertColumnEx(0, "Title", 150)
  ...

AddStyle

                              +-------------------+
                              V                   |
>>-aListControl~AddStyle(--"----+-ICON----------+-+--"--)------><
                                +-SMALLICON-----+
                                +-LIST----------+
                                +-REPORT--------+
                                +-ALIGNLEFT-----+
                                +-ALIGNTOP------+
                                +-AUTOARRANGE---+
                                +-ASCENDING-----+
                                +-DESCENDING----+
                                +-EDIT----------+
                                +-HSCROLL-------+
                                +-VSCROLL-------+
                                +-NOSCROLL------+
                                +-NOHEADER------+
                                +-NOSORTHEADER--+
                                +-NOWRAP--------+
                                +-SINGLESEL-----+
                                +-SHOWSELALWAYS-+
                                +-SHAREIMAGES---+
                                +-GROUP---------+
                                +-HIDDEN--------+
                                +-NOTAB---------+
                                +-NOBORDER------+


The AddStyle method adds new window styles to a list view control.

Arguments:

The only argument is:

style

The window styles to be added, which is one or more of the styles listed in the syntax diagram, separated by blanks. For an explanation of the different styles, refer to AddListControl.

Return value:

0 if this method fails.

RemoveStyle

                                 +-------------------+
                                 V                   |
>>-aListControl~RemoveStyle(--"----+-ICON----------+-+--"--)---><
                                   +-SMALLICON-----+
                                   +-LIST----------+
                                   +-REPORT--------+
                                   +-ALIGNLEFT-----+
                                   +-ALIGNTOP------+
                                   +-AUTOARRANGE---+
                                   +-ASCENDING-----+
                                   +-DESCENDING----+
                                   +-EDIT----------+
                                   +-HSCROLL-------+
                                   +-VSCROLL-------+
                                   +-NOSCROLL------+
                                   +-NOHEADER------+
                                   +-NOSORTHEADER--+
                                   +-NOWRAP--------+
                                   +-SINGLESEL-----+
                                   +-SHOWSELALWAYS-+
                                   +-SHAREIMAGES---+
                                   +-GROUP---------+
                                   +-HIDDEN--------+
                                   +-NOTAB---------+
                                   +-NOBORDER------+


The RemoveStyle method removes one or more window styles of a list view control.

Arguments:

The only argument is:

style

The window styles to be removed, which is one or more of the styles listed in the syntax diagram, separated by blanks. For an explanation of the different styles, refer to AddListControl.

Return value:

0 if this method fails.

AddExtendedStyle

                                     +--------------------+
                                     V                    |
>>-aListControl~AddExtendedStyle(--"---+-BORDERSELECT-----+--"--)------------><
                                       +-CHECKBOXES-------+
                                       +-DOUBLEBUFFER-----+
                                       +-FLATSB-----------+
                                       +-FULLROWSELECT----+
                                       +-GRIDLINES--------+
                                       +-HEADERDRAGDROP---+
                                       +-INFOTIP----------+
                                       +-LABELTIP---------+
                                       +-MULTIWORKAREAS---+
                                       +-ONECLICKACTIVATE-+
                                       +-REGIONAL---------+
                                       +-SIMPLESELECT-----+
                                       +-SUBITEMIMAGES----+
                                       +-TRACKSELECT------+
                                       +-TWOCLICKACTIVATE-+
                                       +-UNDERLINECOLD----+
                                       +-UNDERLINEHOT-----+

The AddExtendedStyle method adds one or more of the extended List-View styles to a ListControl. These styles can not be added until the underlying Windows List-View control has been created. They can be added in the InitDialog method or any time thereafter.

Arguments:

The only argument is:

style

The extended styles to be added. This argument is a list containing one or more of the following style keywords, separated by blanks. Invalid words in the list are ignored. If there are no valid keywords at all in the list, then an error is returned.

BORDERSELECT

When an item is selected the border color of the item changes rather than the item being highlighted.

CHECKBOXES

Check boxes are visible and functional in all list view modes except tile mode.

DOUBLEBUFFER

Windows XP or later only. The list-view control is painted using double buffering. This reduces flicker.

FLATSB

Enables flat scroll bars.

FULLROWSELECT

Report view only. When a row is selected, the whole row is highlighted rather than just the first column.

GRIDLINES

Report view only. Gridlines are drawn around all items and sub-items. This gives a spreadsheet-like appearance to the list view control.

HEADERDRAGDROP

Report view only. The user can drag and drop the headers to rearrange the columns.

INFOTIP

With this style a notification is sent to the parent window before displaying an item's tooltip. (The current version of ooDialog can not take advantage of this style. It is planned for a future enhancement.)

LABELTIP

Windows XP or later only. In any list view mode, if an item's label is only partially visible, the complete label will be displayed in a fashion similar to a tool tip.

MULTIWORKAREAS

The current version of ooDialog can not take advantage of this style. It is planned for a future enhancement.

ONECLICKACTIVATE

Enables the list-view control to send an item activate notification when the user clicks one time on an item. It also enables hot tracking in the list-view control. Both the underline cold and the underline hot styles need either one click activate or two click activate styles to be enabled.

REGIONAL

Icon view only. Sets the window region to only include an item's icon and text.

SIMPLESELECT

Windows XP and later only. Icon view only. Moves the state image to the top right of the icon image. If the user changes the state using the space bar, all the selected items cycle, not just the item with the focus.

SUBITEMIMAGES

Report view only. Allows images to be displayed for subitems.

TRACKSELECT

Enables hot track selection. The user can select an item by leaving the mouse over an item for a certain period of time, the "hover" time. This period of time can be changed from the default by using the SetHoverTime method.

TWOCLICKACTIVATE

Enables the list-view control to send an item activate notification when the user clicks on an item after it has been selected. When the user clicks on an item it will be selected. At that point, if the user clicks on the item a second time, the item will be activated. Note that this is different from double-clicking to activate. Any amount of time can pass between the click that selects the item and the click that activates the item. (Provided the item remains selected of course.)

It also works with track select. If track select is enabled, the user can select an item by pausing the mouse over the item. At that point, if the user then clicks on the item it will be activated.

UNDERLINECOLD

Underlining gives the user a visual clue that a single click on an item will activate it. Underlining requires either ONECLICKACTIVATE or TWOCLICKACTIVE to also be enabled. An item becomes hot when the mouse is over it. Underline cold underlines all the cold items when a single click will activate them. When one click activate is enabled, this would then be all items. When two click activate is enabled this would then be only those items that were selected.

UNDERLINEHOT

The underline hot style is similar to the underline cold style. See that style above for the explanation of some of the terms. With underline hot, the item is underlined when the mouse is over it, if one click will activate the item.

Return value:

The return values are:

0

Success.

-1

An (internal) problem with the control's window handle.

-3

The style argument did not contain any of the extended style keywords.

Example:

The following example shows how to initially add the extended styles to a list view control. This is done in the InitDialog method, which executes after the underlying Windows dialog has been created, but before it is displayed on the screen. This is the earliest point in time that the extended style methods can be used. The list view is in the report view and will have check boxes and grid lines. The user will be able to use drag and drop to rearrange the columns. When a row is selected, the full row will be highlighted rather than just the first column.

 

::method initDialog
  expose listView

  ...
  listView = self~getListControl(IDC_LIST)
  if listView == .nil then return

  listView~addExtendedStyle("CHECKBOXES GRIDLINES FULLROWSELECT HEADERDRAGDROP")
  ...

RemoveExtendedStyle

                                         +--------------------+
                                         V                    |
>>-aListControl~RemoveExtendedStyle(--"----+-BORDERSELECT-----+--"--)-------><
                                           +-CHECKBOXES-------+
                                           +-DOUBLEBUFFER-----+
                                           +-FLATSB-----------+
                                           +-FULLROWSELECT----+
                                           +-GRIDLINES--------+
                                           +-HEADERDRAGDROP---+
                                           +-INFOTIP----------+
                                           +-LABELTIP---------+
                                           +-MULTIWORKAREAS---+
                                           +-ONECLICKACTIVATE-+
                                           +-REGIONAL---------+
                                           +-SIMPLESELECT-----+
                                           +-SUBITEMIMAGES----+
                                           +-TRACKSELECT------+
                                           +-TWOCLICKACTIVATE-+
                                           +-UNDERLINECOLD----+
                                           +-UNDERLINEHOT-----+

The RemoveExtendedStyle method removes one or more extended styles of a List-View control.

Arguments:

The only argument is:

style

The extended style(s) to be removed. This is one or more of the styles listed in the syntax diagram, separated by blanks. For an explanation of the different styles, refer to the AddExtendedStyle method.

Return value:

The return values are:

0

Success.

-1

An (internal) problem with the control's window handle.

-3

The style argument did not contain any of the extended style keywords.

Example:

The following example removes the check box style from the list view.


  listView = self~getListControl(IDC_LIST)
  if listView == .nil then return

  listView~removeExtendedStyle("CHECKBOXES")

ReplaceExtendedStyle

                                                     +--------------------+
                                                     V                    |
>>-aListControl~ReplaceExtendedStyle(-oldStyle--,--"---+-BORDERSELECT-----+--"-)-><
                                                       +-CHECKBOXES-------+
                                                       +-DOUBLEBUFFER-----+
                                                       +-FLATSB-----------+
                                                       +-FULLROWSELECT----+
                                                       +-GRIDLINES--------+
                                                       +-HEADERDRAGDROP---+
                                                       +-INFOTIP----------+
                                                       +-LABELTIP---------+
                                                       +-MULTIWORKAREAS---+
                                                       +-ONECLICKACTIVATE-+
                                                       +-REGIONAL---------+
                                                       +-SIMPLESELECT-----+
                                                       +-SUBITEMIMAGES----+
                                                       +-TRACKSELECT------+
                                                       +-TWOCLICKACTIVATE-+
                                                       +-UNDERLINECOLD----+
                                                       +-UNDERLINEHOT-----+


The ReplaceExtendedStyle method removes some of the List-View control's extended styles and adds new extended styles. This is the equivalent of first using the RemoveExtendeStyle method and then using the AddExtendedStyle method.

Arguments:

The arguments are:

oldStyle

The extended style(s) to be removed. This is one or more of the styles listed in the syntax diagram, separated by blanks. For an explanation of the different styles, refer to the AddExtendedStyle method.

newStyle

The extended style(s) to be added. Again, this is one or more of the styles listed in the syntax diagram, separated by blanks. See the AddExtendedStyle method for the style descriptions.

Return value:

The return values are:

0

Success.

-1

An (internal) problem with the control's window handle.

-3

One, or both, of the style arguments had none of the extended style keywords.

Example:

The following example removes the cold and hot underlining and adds check boxes to the list view.


  listView = self~getListControl(IDC_LIST)
  if listView == .nil then return

  removeStyle = "UNDERLINECOLD UNDERLINEHOT"
  addStyle = "CHECKBOXES"

  listView~replaceExtendedStyle(removeStyle, addStyle)

GetExtendedStyle

>>-aListControl~GetExtendedStyle---------------------------------------------><

The GetExtendedStyle method returns the extended styles of a ListControl. The styles are returned as a string of blank delimited style keywords. These are the same keywords as those used to set the styles.

Arguments:

This method takes no arguments.

Return value:

The returned string can contain one or more of the following style keywords. See the AddExtendedStyle method for the style descriptions:

  • BORDERSELECT

  • CHECKBOXES

  • DOUBLEBUFFER

  • FLATSB

  • FULLROWSELECT

  • GRIDLINES

  • HEADERDRAGDROP

  • INFOTIP

  • LABELTIP

  • MULTIWORKAREAS

  • ONECLICKACTIVATE

  • REGIONAL

  • SIMPLESELECT

  • SUBITEMIMAGES

  • TRACKSELECT

  • TWOCLICKACTIVATE

  • UNDERLINECOLD

  • UNDERLINEHOT

Example:

The following example comes from a fictious application where the user can elect to use the track select style, or not. With this style, an item can be selected by pausing the mouse over it for a period of time specified by the hover time. The application also allows the user to increase or decrease the hover time. In this example when the methods to increment or decrement the hover time are invoked, the application first checks to see if the list view control has the track select style. Then the change is only made if the list view control does have the style.

 

::method initDialog
  expose listView

  ...
  listView = self~getListControl(IDC_LIST)
  if listView == .nil then return

  listView~addExtendedStyle("CHECKBOXES FULLROWSELECT TRACKSELECT")
  ...

::method onCheckboxClick
  expose listView

  chkBox = self~getCheckControl(IDC_CHECK_USETRACKSELECT)
  if chkBox~checked then
    listView~addExtendedStyle("TRACKSELECT")
  else
    listView~removeExtendedStyle("TRACKSELECT")

::method onDecrement
  expose listView

  styles = listView~getExtendedStyle
  if styles~wordpos("TRACKSELECT") == 0 then return

  time = listView~getHoverTime - 100
  if time > 0 then listView~setHoverTime(time)

::method onIncrement
  expose listView

  styles = listView~getExtendedStyle
  if styles~wordpos("TRACKSELECT") == 0 then return

  -- Let the user increase the hover time to any length they want.
  listView~setHoverTime(list~getHoverTime + 100)

GetExtendedStyleRaw

>>-aListControl~GetExtendedStyleRaw------------------------------------------><

The GetExtendedStyleRaw method returns the extended styles of a ListControl as the numeric value of the extended style flags. This method is provided for programmers familiar with the Windows API who may wish to know, or to work with, the actual value of the flags.

Arguments:

This method takes no arguments.

Return value:

The returned value is the numeric value of the extended style flags currently in effect for the list-view control.

Example:

The following example is the same example as the GetExtendedStyle example. It simply replaces the GetExtendedStyle invocation with a GetExtendedStyleRaw invocation.

 

::method initDialog
  expose listView

  ...
  listView = self~getListControl(IDC_LIST)
  if listView == .nil then return

  listView~addExtendedStyle("CHECKBOXES FULLROWSELECT TRACKSELECT")
  ...

::method onCheckboxClick
  expose listView

  chkBox = self~getCheckControl(IDC_CHECK_USETRACKSELECT)
  if chkBox~checked then
    listView~addExtendedStyle("TRACKSELECT")
  else
    listView~removeExtendedStyle("TRACKSELECT")

::method onDecrement
  expose listView

  if .DlgUtil~and(listView~getExtendedStyleRaw, "0x00000008") == 0 then return

  time = listView~getHoverTime - 100
  if time > 0 then listView~setHoverTime(time)

::method onIncrement
  expose listView

  if .DlgUtil~and(listView~getExtendedStyleRaw, "0x00000008") == 0 then return

  -- Let the user increase the hover time to any length they want.
  listView~setHoverTime(list~getHoverTime + 100)

GetHoverTime

>>-aListControl~GetHoverTime-----------------------------------><

This method retrieves the current hover time. The hover time is expressed as milliseconds. The hover time only affects list view controls that have the track select, one click activate, or two click activate extended list view styles. See the AddExtendedStyle for a description of these styles.

Arguments:

This method takes no arguments

Return value:

The hover time. A value of -1 indicates the hover time is the system default hover time.

Example:

The following example comes from a program where the one click activate and track select styles are enabled. Orignally the hover time is set to .4 seconds. However the application allows the users to increase or decrease this time to match their preference. A menu item (or a button could be used) is connected to the onIncrement and onDecrement methods. When either of the methods is invoked, the current hover time is examined and then either incremented or decremented by .1 of a second.

 

::method initDilaog
  expose list

  ...
  list = self~getListControl(IDC_LIST)
  list~addExtendedStyle("ONECLICKACTIVATE TRACKSELECT FULLROWSELECT")
  list~setHoverTime(400)
  ...

::method onDecrement
  expose list

  time = list~getHoverTime - 100
  if time > 0 then list~setHoverTime(time)

::method onIncrement
  expose list

  -- Let the user increase the hover time to any length they want.
  list~setHoverTime(list~getHoverTime + 100)

SetHoverTime

>>-aListControl~SetHoverTime(--+------+--)---------------------><
                               +-time-+

This method is used to change the hover time. The hover time only affects list view controls that have the track select, one click activate, or two click activate extended list view styles. See the AddExtendedStyle for a description of these styles.

Arguments:

The only optional argument is:

time

Specify the hover time in milliseconds. If this argument is omitted, the hover time is set to the system default. A negative number will also set the hover time back to the system defualt.

Return value:

The previous hover time. A value of -1 indicates the previous hover time was the system default.

Example:

The following example adds the one click activate, the track select, and the full row select extended list view styles to a ListControl. The hover time is set to .4 seconds. If the user pauses his mouse over a row in the list view for .4 of a second the row is automatically selectd.

 
::method initDilaog

  ...
  list = self~getListControl(IDC_LIST)
  list~addExtendedStyle("ONECLICKACTIVATE FULLROWSELECT TRACKSELECT")

  oldTime = list~setHoverTime(400)
  ...

Check

>>-aListControl~Check(--index--)--------------------------------------------><

The Check method sets the check mark for a list view item. This method is only valid for list view controls that have the check boxes extended style. (See the AddExtendedStyle method for a description of the check boxes extended style.)

Arguments:

The only argument is:

index

The index of the item for which to set the check mark.

Return value:

The return values are:

0

Success.

-1

An (internal) problem with the control's window handle.

-2

The list view control does not have the check boxes extended style.

-3

The index is invalid.

Example:

The following example is from a mailing list application. The user selects which entries to include in any mailing. All items in a list view that have their check boxes checked are included in the mailing. The application has a feature that allows the user to automatically select all items with a specified zip code.


::method onUseZip

  text = self~getEditControl(IDC_EDIT_ZIPCODE)~getText
  if self~validateZip(text) then do
     list = self~getListControl(IDC_LIST)
     do i = 0 to addresses~items - 1
       infoTable = address[i + 1]
       if infoTable['zip'] == text then list~check(i)
     end
  end

Uncheck

>>-aListControl~Uncheck(--index--)------------------------------------------><

The Uncheck method removes the check mark for a list view item. This method is only valid for list view controls that have the check boxes extended style. (See the AddExtendedStyle method for a description of the check boxes extended style.)

Arguments:

The only argument is:

index

The index of the item where the check box check is to be removed.

Return value:

The return values are:

0

Success.

-1

An (internal) problem with the control's window handle.

-2

The list view control does not have the check boxes extended style.

-3

The index is invalid.

Example:

The following example is from a doctor's office custom accounting application. A list box is filled with information for every patient. One button in the application checks every patient with an outstanding balance, they will be mailed a statement for that balance. The doctor does not believe in sending billing statements to patients that have a very low balance. However what a "low" balance is depends on how he is feeling at statement time. Therefore the application allows the office manager to dynamically remove some patients from the statement list.


::method onDeferBilling
  expose billingList

  text = self~getEditControl(IDC_EDIT_MINAMOUNT)~getText
  minimun = self~decimalNumber(text)

  if minimum > 0 then do i = 0 to billingList~items
    if billingList~isChecked(i) then do

      -- Column 6 in the list is the patient's current balance.
      owes = billingList~itemText(i, 6)
      if self~decimalNumber(owes) <= minimum then billingList~uncheck(i)

    end
  end

CheckAll

>>-aListControl~CheckAll----------------------------------------------------><

The CheckAll method sets the check mark for every list view item. This method is only valid for list view controls that have the check boxes extended style. (See the AddExtendedStyle method for a description of the check boxes extended style.)

Arguments:

This method takes no arguments.

Return value:

The return values are:

0

Success.

-1

An (internal) problem with the control's window handle.

-2

The list view control does not have the check boxes extended style.

Example:

The following example is from a program that has a push button that allows the user to check all the check boxes:


::method onCheckAll

  list = self~getListControl(IDC_LIST_REPUBLICANS)
  list~checkAll

UncheckAll

>>-aListControl~UncheckAll--------------------------------------------------><

The UncheckAll method clears the check mark for every list view item. This method is only valid for list view controls that have the check boxes extended style. (See the AddExtendedStyle method for a description of the check boxes extended style.)

Arguments:

This method takes no arguments.

Return value:

The return values are:

0

Success.

-1

An (internal) problem with the control's window handle.

-2

The list view control does not have the check boxes extended style.

Example:

The following example is from a program that has a push button that allows the user to remove the check mark from all the check boxes:


::method onUncheckAll

  list = self~getListControl(IDC_LIST_REPUBLICANS)
  list~uncheckAll

GetCheck

>>-aListControl~GetCheck(--index--)-----------------------------------------><

The GetCheck method determines if the item at the specified list index has a checked check box. This method will return a code indicating that the list view control does not have the check boxes extended style, if appropriate. (See the AddExtendedStyle method for a description of the check boxes extended style.)

Arguments:

The only argument is:

index

The index of the item to query.

Return value:

The return values are:

1

The item has a check box that is checked.

0

The item has a check box, and it is not checked.

-1

An (internal) problem with the control's window handle.

-2

The list view control does not have the check boxes extended style.

-3

The index is invalid.

Example:

The following example could be used as a shortcut method to determine if a list view control currently has the check box extended style.


  ...
  list = self~getListControl(IDC_LV_DOCTORS)
  if list~getCheck(0) == -2 then
    return   -- The list view does not currently have the check box style in effect

  do i = 0 to list~items - 1
    ...
  end


IsChecked

>>-aListControl~IsChecked(--index--)----------------------------------------><

The IsChecked method determines if a check box for a list view item is checked or not. This method will always return true or false. It can be used if the list view control has or does not have the check boxes extended style. (See theAddExtendedStyle method for a description of the check boxes extended style.)

Arguments:

The only argument is:

index

The index of the item to query.

Return value:

The return values are:

true

The list view item has a check box and it is checked.

false

There is no check mark for the list view item. Either the list view has check boxes and the check box is not checked, the index is out of range or not valid, or the list view does not have the check box extended style.

Example:

The following example is from a doctor's office custom accounting application. A list box is filled with information for every patient. After the office mananger has finished working with the accounts a mail merge is done to produce statements for all patients that are to receive statements for the month. For every patient item in the list view, if the item has a check mark, then that patient is mailed a statement.

 

::method onCreateMailMerge
  expose patientList

  do i = 0 to patientList~items
    if billingList~isChecked(i) then do
      self~addToMailMerge(billingList, i)
    end
  end

InsertColumn

                               +-0------+
>>-aListControl~InsertColumn(--+--------+--,--text--,-->
                               +-column-+

>--,--width--+---------------------+--)---------------><
             |       +-LEFT---+    |
             +-,--"--+-CENTER-+--"-+
                     +-RIGHT--+


The InsertColumn method sets the attributes of a report list view column.

Arguments:

The arguments are:

column

The number of the column. 0 is the first column and the default.

text

The text of the column heading.

width

The width of the column, in pixels.

align

The alignment of the column heading and the subitem text within the column. It can be one of the following values:

CENTER

The text is centered.

LEFT

The text is left-aligned, which is the default.

RIGHT

The text is right-aligned.

Return value:

The number of the new column, or 0 if this method fails.

Example:

The following example adds three columns to a report list:

::method InitReport
  curList = self~GetListControl(102)
  if curList \= .Nil then
  do
    curList~InsertColumn(0,"First Name",50)
    curList~InsertColumn(1,"Last Name",50)
    curList~InsertColumn(2,"Age",50)
  end

DeleteColumn

>>-aListControl~DeleteColumn(--column--)-----------------------><


The DeleteColumn method removes a column from a list view control.

Arguments:

The only argument is:

column

The number of the column to be deleted. The first column must be deleted last.

Return value:

0

The column was deleted.

-1

You did not specify column.

1

For all other cases.

ModifyColumn

>>-aListControl~ModifyColumn(--column--,--+------+--,--width---->
                                          +-text-+

>--+---------------------+--)----------------------------------><
   |       +-LEFT---.    |
   +-,--"--+-CENTER-+--"-+
           +-RIGHT--+


The ModifyColumn method sets new attributes for a column of a list view control.

Arguments:

The arguments are:

column

The number of the column. 0 is the first column.

text

The text of the column heading. If you omit this argument, the heading is not changed.

width

The width of the column, in pixels.

align

The alignment of the column heading and the subitem text within the column. It can be one of the following values:

CENTER

The text is centered.

LEFT

The text is left-aligned, which is the default.

RIGHT

The text is right-aligned.

Return value:

0

The column was modified.

-1

You did not specify column.

1

For all other cases.

Example:

The following example changes the title, size, and alignment of the first column in a report list:

::method ChangeColumn
  curList = self~GetListControl(102)
  curList~ModifyColumn(0,"New Title",100,"RIGHT")

ColumnInfo

>>-aListControl~ColumnInfo(--column--)-------------------------><


The ColumnInfo method retrieves the attributes of a column of a list view control.

Arguments:

The only argument is:

column

The number of the column of which the attributes are to be retrieved. 0 is the first column.

Return value:

A compound variable that stores the attributes of the item. If attributes for a column are not available or an error occurs, then the RetStem.!WIDTH variable will be set to 0.

RetStem.!TEXT

The heading of the column.

RetStem.!COLUMN

The column number.

RetStem.!WIDTH

The width of the column.

RetStem.!ALIGN

The alignment of the column: "LEFT", "RIGHT", or "CENTER".

Example:

The following example displays the column attributes in an information box when the column is clicked on:


::method onColumnClick
  use arg id, column
  listView = self~getListControl(100)
  info. = listView~columnInfo(column)

  msg = "Column Title : " info.!Text   || .endOfLine || -
        "Column Number: " info.!Column || .endOfLine || -
        "Column Width : " info.!Width  || .endOfLine || -
        "Alignment    : " info.!Align

  call infoDialog msg

ColumnWidth

>>-aListControl~ColumnWidth(--column--)------------------------><


The ColumnWidth method retrieves the width of a column in a report or list view.

Arguments:

The only argument is:

column

The number of the column of which the width is to be retrieved. 0 is the first column.

Return value:

The column width, or -1 if you did not specify column, or 0 in all other cases.

Example:

The following example displays the column width in an information box when the column is clicked on:

::method onColumnClick
  use arg id, column
  listView = self~getListControl(102)
  call infoDialog listView~columnWidth(column)

SetColumnWidth

>>-aListControl~SetColumnWidth(--column--+----------+--)-------><
                                         +-,--width-+


The SetColumnWidth method sets the width of a column in a report or list view.

Arguments:

The arguments are:

column

The number of the column of which the width is to be set. 0 is the first column.

width

The width of the column, in pixels. If you omit this argument, the column is sized automatically.

Return value:

0

The column width was set.

-1

You did not specify column.

1

For all other cases.

Example:

The following example enlarges the selected column by 10:

::method OnColumnClick
  use arg id, column
  curList = self~GetListControl(102)
  curList~SetColumnWidth(column,curList~ColumnWidth(column)+10)

getColumnCount

>>--getColumnCount----------------------------------------------------><

This method returns the number of columns in the list-view control when it is in report view.

Arguments:

There are no arguments.

Return value:

This method returns the number of colunms, or -1 on some error. An error is unlikely.

Example:

This method is straight forward to use:

colCount = list~getColumnCount

getColumnOrder

>>--getColumnOrder----------------------------------------------------><

Retrieves the current column order of the list-view when in report view. The order of the columns can be changed programmatically by using the setColumnOrder() method. In XP and later there is also an extended style which lets the user rearrange the order of the columns. If the list-view control has not had the columns rearranged, then the column order will always be 0, 1, 2, ... of course.

One practical use of this method would be in conjuction with the setColumnOrder() method. In an application where the user can rearrange the column order, the programmer could get the order when a dialog closes, save it, and then restore the order to the user's preference when the application is restarted.

Note that the list-view control does not have to have the HEADERDRAGDROP style for the get and set column order methods to work. That style is only needed to allow the user to rearrange the columns using drag and drop. The programmer can use setColumnOrder() to change the order of the columns whether or not the list-view has the HEADERDRAGDROP style, or not.

Arguments:

There are no arguments.

Return value:

The possible return values are:

an .Array object

An array is returned with the index numbers of the columns. The number at the first position in the array is the column index of the left-most column. The number in the second position in the array is the index of the second left-most column, etc..

.nil

.nil is returned for some unexpected error. This is unlikely.

Example:

This example prints out the column order when the dialog is first initialized, and then prints out the order when the dialog closes.

  ...
  list = self~getListControl(100)

  columnNames = .array~of("Occupation", "Name", "Age", "Sex")
  list~addExtendedStyle("FULLROWSELECT GRIDLINES CHECKBOXES HEADERDRAGDROP")

  list~InsertColumn(0, columnNames[1], 95)
  list~InsertColumn(1, columnNames[2], 95)
  list~InsertColumn(2, columnNames[3], 95)
  list~InsertColumn(3, columnNames[4], 35)

  self~printColumnOrder
  ...

::method close

  self~printColumnOrder
  return self~ok:super

::method printColumnOrder private
  expose list columnNames

  cols = list~getColumnOrder
  say 'cols:' cols
  say 'Column count: ' list~getColumnCount
  say 'Current order:'
  if cols~isA(.array) then do c over cols
    -- Column indexes are zero-based
    c += 1
    say " " columnNames[c]
  end

/* Output might be, (assuming the user changed the order):

cols: an Array
Column count:  4
Current order:
  Occupation
  Name
  Age
  Sex

cols: an Array
Column count:
Current order:
  Age
  Name
  Sex
  Occupation

*/

setColumnOrder

>>--setColumnOrder(--order--)-----------------------------------------><

Changes the column order of a list-view control to some other order. Typically this method might be used along with the getColumnOrder() method to save and restore the user's column order. But, it can also be used to programmatically change the column order for any reason.

Details:

Raises syntax errors when incorrect arguments are detected.

Arguments:

The single required argument is:

order

An array containing the index numbers of the columns in their new order. The number at the first position in the array is the column index of the column that should be the left-most. The number at the second position in the array, and so on.

The array has to contain the same number of items as the number of columns with no empty indexes.

If non-valid column indexes are intermingled with valid column indexes, then the columns are re-ordered, but with no easily predictable pattern. If all the number are invalid column indexes, then the order of the columns remains unchanged. This behavior is the behavior of the underlying control, ooDialog has no control over it.

Return value:

The possible return values are:

.true

The method succeeded.

.false

Some error occurred. This is unlikely.

Example:

In this example an application has two modes. One mode emphasizes the occupation of the people in a database, the other mode emphasizes the people. The order of the columns is occupation, name, ... for the first mode and name, occupation, ... for the second mode. When the mode of the application changes, the order of the columns also changes.

  ...
  list = self~getListControl(100)

  columnNames = .array~of("Occupation", "Name", "Age", "Sex")
  list~addExtendedStyle("FULLROWSELECT GRIDLINES CHECKBOXES")

  list~InsertColumn(0, columnNames[1], 95)
  list~InsertColumn(1, columnNames[2], 95)
  list~InsertColumn(2, columnNames[3], 95)
  list~InsertColumn(3, columnNames[4], 35)
  ...

::method toggleColumnOrder private
  expose list

  order = list~getColumnOrder
  tmp = order[1]
  order[1] = order[2]
  order[2] = tmp
  list~setColumnOrder(order)

StringWidth

>>-aListControl~StringWidth(--text--)--------------------------><


The StringWidth method determines the width of a specified string using the current font of the list view control.

Arguments:

The only argument is:

text

The text string of which the width is to be determined.

Return value:

The string width, or -1 if you did not specify a text, or 0 in all other cases.

insert

>>--insert(--+------+--,--+---------+--,--text--+--------+--)------------------><
             +-item-+     +-subitem-+           +-,-icon-+

The insert method inserts a new item into the list-view control, or inserts the text of a subitem.

Remember that in a list-view, items and columns use a 0-based index. Subitems use a 1-based index.

Arguments:

The arguments are:

item

The index of the item to insert or the item whose subitem text is inserted.

When this argument is omitted and subitem is omitted or 0, ooDialog uses the index of the last item added to the list-view control, plus 1, as the item index. If the argument is omitted and subitem is greater than 0, then the index of the last item added is used. If no items have yet been added, then 0 is used.

subitem

The subitem number. This argument is used to insert the text for a subitem of the item. In report view, the label (text) for the item is placed in column 0. The text for subitem 1 is placed in column 1, the text for subitem 2 is placed in column 2, and so on. If you omit this argument, or use 0, the the text argument is assigned as the label (text) of the item. If you use this argument and it is greater than 0, then the text argument is assigned as the text of that subitem. Note that when this argument is greater than 0, no new item is inserted into the list-view. Rather, the text of the subitem is inserted into an existing list-view item.

text

The text of the item, or of the subitem, depending on the subitem argument.

icon

The index of the icon within the image list for this item. Use the setImageList() method to assign an image list to the list-view control. With setImageList(), use the LVSIL_SMALL type to set the image list for the small icons and the LVSIL_NORMAL type for the normal size icon image list.

The normal size icons are used for the icon view and the small icons are used for the list, report, and small-icon views. Note that there is only one index for each list-view item. This implies that the normal icon for an item must be at the same index in the normal image list as the small icon is at in the small icon image list.

Use -1 or simply omit this argument to indicate there is no icon for the item being inserted. This argument is ignored completely if subitem is greater than 0.

Return value:

The index of the new item, or -1 in all other cases.

Example:

The following example inserts items in a list:

::method initReport
  curList = self~getListControl(102)
  if curList \= .nil then
  do
    curList~insert(, ,"First")
    curList~insert(, ,"Second")
    curList~insert(, ,"Third")
  end

modify

>>--modify(--+------+--,--+---------+--,--text--+--------+--)------------------><
             +-item-+     +-subitem-+           +-,-icon-+

The modify method modifies or sets the text for the item label, or the text for a subitem, for a list-view item. Optionally, it sets or modifies the icon index for a list-view item.

Remember that in a list-view, items and columns use a 0-based index. Subitems use a 1-based index.

Arguments:

The arguments are:

item

The index of the item to be modified. If you omit this argument, the selected item is used.

subitem

This method works in a similar manner as the insert() method. The use of the subitem argument controls whether the text argument applies to the label of the item or the text of a subitem. When subitem is omitted or 0, then the label of the item is set to text. When subitem is greater than 0, then the text of that subitem is set to text.

text

The new text for the item label, or the new text for the subitem of the item, depending on the value of subitem.

icon

The new index of the icon for the item within the image list assigned to the list-view. Image lists are assigned with the setImageList() method. When assigning the image list with setImageList(), use the LVSIL_NORMAL flag for the icon view icons and the LVSIL_SMALL flag for the list, report, and small-icon view icons.

Use -1 or simply omit this argument to leave the icon index unchanged. If subitem is greater than 0, this argument is ignored.

Return value:

0

The modification was successful.

1

For all other cases.

Example:

The following example modifies the icon for an item when it is activated. A method, onActivate, is connected to the ACTIVATE notification. When an item is activated it also gains the focus. The onActivate() method is invoked when an item is activated, and the example determines which item was activated by seeing which item has the focus.


::method initDialog
  expose list

  list  = self~getListControl(IDC_LV_VIEWS)
  self~connectListNotify(IDC_LV_VIEWS, 'ACTIVATE', 'onActivate')

  ...

::method onActivate
  expose list

  focusedItem = list~focused
  text = list~itemText(focusedItem)

  list~modify(focusedItem, , text, 2)

setItemText

>>--setItemText(--item--,--+-----------+--,--text--)--><
                           +--subitem--+

The setItemText method changes the text of a label, or the text of a subitem, of a list view item.

Remember that in a list-view, items and columns use a 0-based index. Subitems use a 1-based index.

Arguments:

The arguments are:

item

The index of the item.

subitme

This method works in a similar manner as the insert() method. The use of the subitem argument controls whether the text argument applies to the label of the item or the text of a subitem. When subitem is omitted or 0, then the label of the item is set to text. When subitem is greater than 0, then the text of that subitem is set to text.

text

The text for the item or a subitem, depending on the value of subitem.

Return value:

0

The change was successful.

-1

You did not specify item.

1

For all other cases.

SetItemState

>>-aListControl~SetItemState(--item--+------------------------------+--)-><
                                     |       +-----------------+    |
                                     |       V                 |    |
                                     +-,--"----+-CUT---------+-+--"-+
                                               +-NOTCUT------+
                                               +-DROP--------+
                                               +-NOTDROP-----+
                                               +-FOCUSED-----+
                                               +-NOTFOCUSED--+
                                               +-SELECTED----+
                                               +-NOTSELECTED-+


The SetItemState method sets the state of a list view item.

Arguments:

The arguments are:

item

The number of the item.

state

The state of the item, which can be one or more of the following values, separated by blanks:

CUT

The item is marked for a cut-and-paste operation.

NOTCUT

The item cannot be used for a cut-and-paste operation.

DROP

The item is highlighted as a drag-and-drop target.

NOTDROP

The item is not highlighted as a drag-and-drop target.

FOCUSED

The item has the focus and is therefore surrounded by the standard focus rectangle. Only one item can have the focus.

NOTFOCUSED

The item does not have the focus.

SELECTED

The item is selected. Its appearance depends on whether it has the focus and on the system colors used for a selection.

NOTSELECTED

The item is not selected.

Return value:

0

The state was set successfully.

-1

You did not specify item.

1

For all other cases.

add

          +-------+
          V       |
>>--add(----+-----+--text--+--------+--)-------><
            +--,--+        +-,-icon-+

The add method adds a new item to a list-view, or defines the text for a subitem. It can be used to fill a list-view sequentially.

Remember that in a list-view, items and columns use a 0-based index. Subitems use a 1-based index.

The number of commas preceding the text argument determines whether a new item is added to the list-view or the text for a subitem is being defined. When there is no comma preceding text then a new item is added to the list-view.

When 1 or more commas precede text, then no item is added to the list-view. Rather, the text for a subitem is defined. When 1 comma precedes text, then the text for subitem 1 is being defined. When 2 commas precedes the text argument, then the text for subitem 2 is being defined, and so on.

When an item is added, it is always added directly after the last item to be placed in the list-view. Or as item 0 if the list-view currently has no items. When the text of a subitem is being defined, then the text is defined for the subitem of last item placed in the list-view.

Arguments:

The arguments are:

,

As explained above, this argument determines if an item is added to the list-view, or if the text of a subitem is defined.

text

The text for the item label, or the text for the subitem of a item, depending on whether an item is being added or the text for a subitem is being defined.

icon

Specifies the index within the image list for the icon for this item. Image lists are assigned to a list-view by using the setImageList() method. With the setImageList() method, use the LVSIL_NORMAL flag for the icon view icons and the LVSIL_SMALL flag for the list, report, and small-icon view icons.

Use -1 or simply omit this arugment to indicate there is no icon for the item being added. This argument is ignored completely when the text for a subitem is being defined.

Example:

The following example adds three columns and two items to a report list control. To get the following result:

First NameLast NameAge
MikeMiller30
SueThaxtor29

using the add() method you must specify something similar to the following:

::method initDialog

  curList = self~getListControl(IDC_LIST_REP)
  if curList \= .nil then do
    imageList = .ImageList~create(.Size~new(16), .Image~toID(ILC_COLOR24), 9, 0)
    imageList~add(.Image~getImage("E:\oodlist\oodlist.BMP"))
    list~setImageList(imageList, .Image~toID(LVSIL_SMALL))

    curList~insertColumn(0,"First Name",50)
    curList~insertColumn(1,"Last Name",50)
    curList~insertColumn(2,"Age",50)

    -- 3 is the index in the image list for the icon for item 0
    curList~add("Mike", 3)
    curList~add(,"Miller")
    curList~add(, ,"30")

    -- 0 is the index in the image list for the icon for item 1
    curList~~add("Sue", 0)~~add(,"Thaxton")~~add(, ,"29")
  end

addRow

                                   +-,----+
                                   V      |
>>--addRow(--+------+--,--icon--,----text-+--)-----><
             +-item-+

The addRow method adds a new item to a list-view. This method is most useful when adding items that have subitems to the list-view. But, despite its name, it can be used to add any item, with or without subitems, to a list-view.

Remember that in a list-view, items and columns use a 0-based index. Subitems use a 1-based index.

Arguments:

The arguments are:

item

The index of the item. If you omit this argument, the item is added immediately after the last item added or inserted in the list-view. That is, the index defaults to the index of the last item added plus 1. If there are no items in the list-view then the item is added at index 0.

icon

The index within the image list for the icon for this item. Image lists are assigned to a list-view by using the setImageList() method. With the setImageList() method, use the LVSIL_NORMAL flag for the icon view icons and the LVSIL_SMALL flag for the list, report, and small-icon views icons.

text

Any number of text strings. The first text string is used for the label of the item. Successive strings are used for the text of subitems of the item. For example, the text of the second string is used for the text of subitem 1. The text of the third string is used for the text of subitem 2, and so on. If the first string is omitted, then the empty string is used for the item label. If other strings are omitted, than no text is set for the corresponding subitem. If you specify more text entries than there are columns, the extra entries are ignored.

Return value:

The index of the new item, or -1 in all other cases.

Example:

The following example adds three items to a report list with two columns:

::method InitList
  curList = self~GetListControl(101)
  curList~addRow(, ,"Mike","Miller")
  curList~addRow(, ,"Sue","Muller")
  curList~addRow(, ,"Chris","Watson")

Delete

>>-aListControl~Delete(--item--)-------------------------------><


The Delete method removes an item from a list view control.

Arguments:

The only argument is:

item

The number of the item.

Return value:

0

The item was deleted.

-1

You did not specify item.

1

For all other cases.

Example:

The following example deletes the selected item in a list control:

::method DeleteSelectedItem
  curList = self~GetListControl(102)
  curList~Delete(curList~Selected)

DeleteAll

>>-aListControl~DeleteAll--------------------------------------><


The DeleteAll method removes all items from a list view control.

Return value:

0

The items were deleted.

-1

No item was available.

1

For all other cases.

Items

>>-aListControl~Items------------------------------------------><


The Items method retrieves the number of items in a list view control.

Return value:

The number of items.

Last

>>-aListControl~Last-------------------------------------------><


The Last method retrieves the number of the last item in a list view control.

Return value:

The number of the last item.

Prepare4nItems

>>-aListControl~Prepare4nItems(--items--)----------------------><


The Prepare4nItems method prepares a list view control for adding a large number of items.

Arguments:

The only argument is:

items

The number of the items to be added later.

Return value:

0

The list view control was prepared.

-1

You did not specify items.

SelectedItems

>>-aListControl~SelectedItems----------------------------------><


The SelectedItems method determines the number of selected items in a list view control.

Return value:

The number of selected items.

ItemInfo

                                    +-0------+
>>-aListControl~ItemInfo(--item--,--+--------+--)--------------><
                                    +-column-+


The ItemInfo method retrieves the attributes of a list view item.

Arguments:

The arguments are:

item

The number of the item.

column

The number of the column. If you omit this argument, 0 is assumed.

Return value:

A compound variable that stores the attributes of the item, or -1 in all other cases. The compound variable can be:

RetStem.!TEXT

The item text.

RetStem.!IMAGE

The index of the icon in the image list this for item. Image lists are assigned to list-views using the setImageList() method.

In report view, this index is only used for the icon for the first column. ooDialog does not yet support setting the icon index for the other columns in a report view.

RetStem.!STATE

One or more of the following values:

CUT

The item is marked for a cut-and-paste operation.

DROPPED

The item is highlighted as a drag-and-drop target.

FOCUSED

The item has the focus and is therefore surrounded by the standard focus rectangle. Only one item can have the focus.

SELECTED

The item is selected. Its appearance depends on whether it has the focus and on the system colors used for a selection.

Example:

The following example displays the item text, icon index, and the item state in a message box:


::method displayItemInfo

  listView = self~getListControl(100)
  item = listView~selected
  if item == -1 then do
    msg = "No item selected."
  end
  else do
    itemInfo. = listView~itemInfo(item)

    msg = "Item Text   : " itemInfo.!Text   || .endOfLine || -
          "Image Index : " itemInfo.!Image  || .endOfLine || -
          "Item State  : " itemInfo.!State
  end

  call infoDialog msg

ItemText

                                    +-0------+
>>-aListControl~ItemText(--item--,--+--------+--)--------------><
                                    +-column-+


The ItemText method retrieves the text of a list view item or a column.

Arguments:

The arguments are:

item

The number of the item.

column

The number of the column. If you omit this argument, 0 is assumed.

Return value:

The item or column text, or -1 if you did not specify item.

ItemState

>>-aListControl~ItemState(--item--)----------------------------><


The ItemState method retrieves the state of a list view item.

Arguments:

The only argument is:

item

The number of the item.

Return value:

The state of the item, which can be one or more of the following values:

CUT

The item can be used in a cut-and-paste operation.

DROPPED

The item is highlighted as a drag-and-drop target.

FOCUSED

The item has the focus and is therefore surrounded by the standard focus rectangle. Only one item can have the focus.

SELECTED

The item is selected. Its appearance depends on whether it has the focus and on the system colors used for a selection.

Select

>>-aListControl~Select(--item--)-------------------------------><


The Select method selects an item.

Arguments:

The only argument is:

item

The number of the item.

Return value:

0

The item was selected.

-1

You did not specify item.

1

For all other cases.

Deselect

>>-aListControl~Deselect(--item--)-----------------------------><


The Deselect method deselects an item.

Arguments:

The only argument is:

item

The number of the item.

Return value:

0

The item was selected.

-1

You did not specify item.

1

For all other cases.

Selected

>>-aListControl~Selected---------------------------------------><


The Selected method returns the number of the selected item.

Return value:

The number of the item selected last, or -1 in all other cases.

LastSelected

>>-aListControl~LastSelected-----------------------------------><


The LastSelected method returns the number of the item selected last.

Return value:

The number of the item selected last, or -1 in all other cases.

Focused

>>-aListControl~Focused----------------------------------------><


The Focused method retrieves the number of the item that has currently the focus.

Return value:

The number of the item with the focus, or -1 in all other cases.

Focus

>>-aListControl~Focus(--item--)--------------------------------><


The Focus method assigns the focus to the specified item, which is then surrounded by the standard focus rectangle. Although more than one item can be selected, only one item can have the focus.

Arguments:

The only argument is:

item

The number of the item to receive the focus.

Return value:

0

The specified item received the focus.

-1

You did not specify item.

1

For all other cases.

DropHighlighted

>>-aListControl~DropHighlighted--------------------------------><


The DropHighlighted method retrieves the item that is highlighted as a drag-and-drop target.

Return value:

The number of the selected item, or -1 in all other cases.

FirstVisible

>>-aListControl~FirstVisible-----------------------------------><


The FirstVisible method retrieves the number of the first item visible in a list or report view.

Return value:

The number of the first item visible, or 0 if the list view control is in icon or small-icon view.

NextSelected

>>-aListControl~NextSelected(--item--)-------------------------><


The NextSelected method retrieves the selected item that follows, or is to the right of, item.

Arguments:

The only argument is:

item

The number of the item at which the search is to start. The specified item itself is excluded from the search.

Return value:

The number of the selected item, or -1 in all other cases.

PreviousSelected

>>-aListControl~PreviousSelected(--item--)---------------------><


The PreviousSelected method retrieves the selected item that precedes, or is to the left of, item.

Arguments:

The only argument is:

item

The number of the item at which the search is to start. The specified item itself is excluded from the search.

Return value:

The number of the selected item, or -1 in all other cases.

Next

>>-aListControl~Next(--item--)---------------------------------><


The Next method retrieves the item that follows, or is to the right of, item.

Arguments:

The only argument is:

item

The number of the item at which the search is to start.

Return value:

The number of the following item, or -1 in all other cases.

Previous

>>-aListControl~Previous(--item--)-----------------------------><


The Previous method retrieves the item that precedes, or is to the left of, item.

Arguments:

The only argument is:

item

The number of the item at which the search is to start.

Return value:

The number of the previous item, or -1 in all other cases.

NextLeft

>>-aListControl~NextLeft(--item--)-----------------------------><


The NextLeft method retrieves the item left to item.

Arguments:

The only argument is:

item

The number of the item at which the search is to start. The specified item itself is excluded from the search.

Return value:

The number of the next item to the left, or -1 in all other cases.

NextRight

>>-aListControl~NextRight(--item--)----------------------------><


The NextRight method retrieves the item right to item.

Arguments:

The only argument is:

item

The number of the item at which the search is to start. The specified item itself is excluded from the search.

Return value:

The number of the next item to the right, or -1 in all other cases.

SmallSpacing

>>-aListControl~SmallSpacing-----------------------------------><


The SmallSpacing method determines the spacing between items in a small-icon list view control.

Return value:

The amount of spacing between the items.

Spacing

>>-aListControl~Spacing----------------------------------------><


The Spacing method determines the spacing between items in an icon list view control.

Return value:

The amount of spacing between the items.

RedrawItems

>>-aListControl~RedrawItems--+--------------------------+------><
                             +-(--first--+---------+--)-+
                                         +-,--last-+


The RedrawItems method forces a list view control to redraw a range of items.

Arguments:

The arguments are:

first

The number of the first item to be redrawn. The default is 0.

last

The number of the last item to be redrawn. The default is 0.

Return value:

0

The specified range of items was redrawn.

1

For all other cases.

UpdateItem

>>-aListControl~UpdateItem(--item--)---------------------------><


The UpdateItem method updates a list view item.

Arguments:

The only argument is:

item

The number of the item to be updated.

Return value:

0

The item was updated.

-1

You did not specify item.

1

For all other cases.

Update

>>-aListControl~Update-----------------------------------------><


The Update method updates a list view control.

Return value:

0.

EnsureVisible

                                         +-0-+
>>-aListControl~EnsureVisible(--item--,--+---+--)--------------><
                                         +-1-+


The EnsureVisible method ensures that a list view item is entirely or partially visible by scrolling the list view control, if necessary.

Arguments:

The arguments are:

item

The number of the item visible.

partial

Specifies whether the item must be entirely visible:

1

The list view control is not scrolled if the item is at least partially visible.

0

The list view control is scrolled if the item is only partially visible. This is the default.

Return value:

0

The item is visible.

-1

You did not specify item.

1

For all other cases.

setImageList

>>--setImageList(--src-+---------------+-+----------+-+----------+-)-----------><
                       +-,-typeOrWidth-+ +-,-height-+ +-,-ilType-+

Assigns, or removes, an image list for the list-view control. Using .nil for the first argument removes the current image list.

The list-view control uses image lists for a number of things, the large icons, the small icons, the state images, and the group header images. (ooDialog does not yet support list-view groups.) The src argument can be either an ImageList object, or a single bitmap.

Using an image list object is the most flexible option. The programmer creates the image list in the manner most suitable to the program. When the program is enhanced or changed it is easy to change the image list.

When src is a single bitmap it is used in this way: A single bitmap is created that consists of all the images for the image list. All the images must be the same width and height. The images are arranged in the bitmap in a row, side-by-side, in the order they should appear in the image list. ooDialog uses this bitmap to create a .ImageList object and assigns it to the list-view. The src argument can be either the file name of the bitmap or a bitmap Image object.

Although using a single bitmap will allow the programmer to save a couple of lines of code, it has a number of disadvantages. The image list is created with the exact number of images in the bitmap and no extra room to add images. The image list is created as an unmasked image list, with a color of 8 bit per pixel. If the program is enhanced or changed in a way that requires even a slight change to the image list, the single bitmap would need to be re-created.

When using a single bitmap, if the system fails to create the image list from the details supplied by ooDialog, the method of informing the programmer of the error is not as robust as it is when the programmer creates the image list herself. However, ooDialog will set the .SystemErrorCode variable for any cases where the operating system reports an error. Also note that when using a single bitmap, ooDialog will instantiate a .ImageList object. The programmer can retrieve this object using the getImageList() method and then manipulate it using the methods of the ImageList class.

Unless a list-view has the LVS_SHAREIMAGELISTS style, (corresponds to the SHAREIMAGES style in the addListControl() method,) the list-view control will handle releasing the image list(s). When the share image lists style is used, ownership of the image list remains with the programmer. The ImageList and Image classes are used to manage image lists and images in ooDialog. The documentation on both classes discusses when and why the programmer may want to release image lists. The Image class documentation has the most detail on this subject.

Details

Sets the .SystemErrorCode variable.

Raises syntax errors when incorrect arguments are detected.

Arguments:

The arguments are:

src

The source for the image list. The most flexible way to use this method is to provide an image list object to assign to the list-view.

However, as explained above, this argument can also be a single bitmap from which the image list is to be created. In this case, the argument can be either the file name of the bitmap or a bitmap Image object.

If this argument is .nil the existing image list, if any, is removed.

typeOrWidth

Optional.

type: When src is an ImageList object, this argument specifies which image list to assign, (or remove.) You can use .Image~toID() to get the correct numeric value for one of the following symbols:

LVSIL_NORMALLVSIL_SMALL
LVSIL_STATE  

or use the correct numeric value itself. Note that there is also a LVSIL_GROUPHEADER symbol, but ooDialog does not yet support it. The default is LVSIL_NORMAL.

width: When src is a single bitmap, this argument can be used to specify the width of a single image in the bitmap. The default is the actual height of the bitmap.

height

Optional. This argument is only used when src is a single bitmap. In that case height specifies the height of an image in the bitmap. The default is to use the actual height of the bitmap.

ilType

Optional. This argument is only used when src is a single bitmap. It is used to specify which image list is being assigned. Its usage is exactly the same as is documented for the type role of the typeOrWidth argument above. If omitted, the default is LVSIL_NORMAL.

Return value:

The existing image list is returned, if there is one. Otherwise, .nil is returned.

Example:

This is a complete working example. It creates an image list using the application icons that ooDialog makes available for general use. The image list is assigned as the normal icon image list.


  dlg = .ImageDisplay~new
  if dlg~initCode = 0 then do
    dlg~constDir[IDC_LV_IMAGES] = 100
    dlg~create(30, 30, 320, 155, "ooDialog Icon Resources", , , "Tahoma")
    dlg~Execute("SHOWTOP", IDI_DLG_OOREXX)
    dlg~Deinstall
  end

::requires "OODWIN32.CLS"

::class 'ImageDisplay' subclass UserDialog inherit AdvancedControls

::method defineDialog

  self~addListControl(IDC_LV_IMAGES, , 10, 10, 300, 135, "ICON SINGLESEL");

::method initDialog

  names = .array~new()
  names[1] = "IDI_DLG_OODIALOG"
  names[2] = "IDI_DLG_APPICON"
  names[3] = "IDI_DLG_APPICON2"
  names[4] = "IDI_DLG_OOREXX"

  ids = .array~new()
  ids[1] = self~constDir[IDI_DLG_OODIALOG]
  ids[2] = self~constDir[IDI_DLG_APPICON]
  ids[3] = self~constDir[IDI_DLG_APPICON2]
  ids[4] = self~constDir[IDI_DLG_OOREXX]

  SM_CXICON = 11
  SM_CYICON = 12

  size = .Size~new(.DlgUtil~getSystemMetrics(SM_CXICON), .DlgUtil~getSystemMetrics(SM_CYICON))

  oodModule = .ResourceImage~new("oodialog.dll", self)
  icons = oodModule~getImages(ids, .Image~toID(IMAGE_ICON), size)

  flags = .DlgUtil~or(.Image~toID(ILC_COLOR24), .Image~toID(ILC_MASK))
  imageList = .ImageList~create(size, flags, 4, 0)
  imageList~addImages(icons)

  list = self~getListControl(IDC_LV_IMAGES)
  list~setImageList(imageList, .Image~toID(LVSIL_NORMAL))

  do i = 1 to ids~items
    list~add(names[i] '('ids[i]')', i - 1)
  end

getImageList

>>--getImageList(--+--------+--)------------------------------------><
                   +--type--+

Retrieves the current image list for the type specified. The default is to retrieve the image list for the normal icons. See the () method for infomation on assigning an image list to a list-view control.

Details

Raises syntax errors when incorrect arguments are detected.

Arguments:

The single optional argument is:

type

Optional. Specifies which image list to retrieve. You can use .Image~toID() to get the correct numeric value for one of the following symbols:

LVSIL_NORMALLVSIL_SMALL
LVSIL_STATE  

or use the correct numeric value itself. Note that there is also a LVSIL_GROUPHEADER symbol, but ooDialog does not yet support it.

The default is LVSIL_NORMAL.

Return value:

This method returns the current image list, if there is one. .nil is returned if there is no current image list of the type specified.

Example:

This example comes from a complex application that opens and closes a large number of dialogs and uses many list-view controls. All the list-view controls share the same image lists. When the last dialog is closed, the shared image lists are released to free up system resources as the application enters its next phase.

::method ok
  self~checkImageLists
  return self~ok:super

::method cancel
  self~checkImageLists
  return self~cancel:super

::method checkImageLists
  expose list

  if self~amLastDialog then do
    types = .array~of(LVSIL_NORMAL, LVSIL_SMALL, LVSIL_STATE)

    do type over types
      il = list~getImageList(type)
      if il \== .nil then il~release
    end
  end

setSmallImages (deprecated)

Note: This method is deprecated. It is replaced by the functionally equivalent setImageList() method. Do not use this method in new code. Try to migrate existing code to to the setImageList() method. This method may not exist in future versions of ooDialog.

setImages (deprecated)

Note: This method is deprecated. It is replaced by the functionally equivalent setImageList() method. Do not use this method in new code. Try to migrate existing code to to the setImageList() method. This method may not exist in future versions of ooDialog.

removeSmallImages (deprecated)

Note: This method is deprecated. It is replaced by the functionally equivalent setImageList() method. Do not use this method in new code. Try to migrate existing code to to the setImageList() method. This method may not exist in future versions of ooDialog.

removeImages (deprecated)

Note: This method is deprecated. It is replaced by the functionally equivalent setImageList() method. Do not use this method in new code. Try to migrate existing code to to the setImageList() method. This method may not exist in future versions of ooDialog.

Find

                                +- -1--+     +-0-+
>>-aListControl~Find(--text--,--+------+--,--+---+--)----------><
                                +-item-+     +-1-+


The Find method searches for a list view item containing text. The text of this item must exactly match text.

Arguments:

The arguments are:

text

The text of the item to be searched for.

item

Specify the number of the item at which the search is to be started. Specify -1 or omit this argument to start the search at the beginning.

wrap

Specify 1 if the search is to be continued at the beginning if no match is found. Specify 0 or omit this argument if the search is to stop at the end of the list.

Return value:

The number of the item, or -1 in all other cases.

FindPartial

                                       +- -1--+     +-0-+
>>-aListControl~FindPartial(--text--,--+------+--,--+---+--)---><
                                       +-item-+     +-1-+


The FindPartial method searches for a list view item containing text. An item matches if its text begins with text.

Arguments:

The arguments are:

text

The text of the item to be searched for.

item

Specify the number of the item at which the search is to be started. Specify -1 or omit this argument to start the search at the beginning.

wrap

Specify 1 if the search is to be continued at the beginning if no match is found. Specify 0 or omit this argument if the search is to stop at the end of the list.

Return value:

The number of the item, or -1 in all other cases.

FindNearestXY

>>-aListControl~FindNearestXY(--x--,--y--+--------------------+--)-><
                                         |       +-DOWN--+    |
                                         +-,--"--+-UP----+--"-+
                                                 +-LEFT--+
                                                 +-RIGHT-+


The FindNearestXY method searches, in the specified direction, for the item nearest to the specified position.

Arguments:

The arguments are:

x

The x-coordinate of the position at which the search is to be started.

y

The y-coordinate of the position at which the search is to be started.

direction

The direction in which the search should proceed.

Return value:

The index of the item, or -1 in all other cases.

Arrange

>>-aListControl~Arrange----------------------------------------><


The Arrange method aligns items according to the current alignment style of the list view control.

Return value:

0

The items were aligned.

1

For all other cases.

SnapToGrid

>>-aListControl~SnapToGrid-------------------------------------><


The SnapToGrid method snaps all icons to the nearest grid position.

Return value:

0

The items were snapped.

1

For all other cases.

AlignLeft

>>-aListControl~AlignLeft--------------------------------------><


The AlignLeft method aligns items along the left window border.

Return value:

0

The items were aligned.

1

For all other cases.

AlignTop

>>-aListControl~AlignTop---------------------------------------><


The AlignTop method aligns items along the upper window border.

Return value:

0

The items were aligned.

1

For all other cases.

ItemPos

>>-aListControl~ItemPos(--item--)------------------------------><


The ItemPos method retrieves the position of the upper left corner of the item.

Arguments:

The only argument is:

item

The number of the item.

Return value:

The x- and y-coordinates of the upper left corner of the item, or -1 if you did not specify item, or 0 in all other cases.

Note: Use DefListDragHandler to support default dragging:

self~ConnectListNotify(104,"BEGINDRAG","DefListDragHandler")

SetItemPos

                                      +-0-+     +-0-+
>>-aListControl~SetItemPos(--item--,--+---+--,--+---+--)-------><
                                      +-x-+     +-y-+


The SetItemPos method moves an item to a specified position in a list view control, which must be in icon or small-icon view.

Arguments:

The arguments are:

item

The number of the item.

x

The x-coordinate of the new position of the upper left corner of the item, in view coordinates. The default is 0.

y

The y-coordinate of the new position of the upper left corner of the item, in view coordinates. The default is 0.

Return value:

0

The item was moved.

-1

You did not specify item.

1

For all other cases.

Note: Use DefListDragHandler to support default dragging:

self~ConnectListNotify(104,"BEGINDRAG","DefListDragHandler")

Edit

>>-aListControl~Edit(--item--)---------------------------------><


The Edit method begins editing of the text of the specified list view item.

Arguments:

The only argument is:

item

The number of the item.

Return value:

The handle of the edit control used to edit the item text, or 0 in all other cases.

EndEdit

>>-aListControl~EndEdit----------------------------------------><


The EndEdit method cancels editing of the list view item that is being edited.

SubclassEdit

>>-aListControl~SubclassEdit-----------------------------------><


The SubclassEdit method is used by the DefListEditHandler to correct an operating system problem if the Esc or Enter key was pressed in an active edit control.

RestoreEditClass

>>-aListControl~RestoreEditClass-------------------------------><


The RestoreEditClass method is used by the DefListEditHandler to correct an operating system problem if the Esc or Enter key was pressed in an active edit item.

ItemsPerPage

>>-aListControl~ItemsPerPage-----------------------------------><


The ItemsPerPage method calculates the number of items that vertically fit the visible area of a list view control that is in list or report view. Only fully visible items are counted.

Return value:

The number of fully visible items. If the current view is an icon or small-icon view, the return value is the total number of items in the list view control.

Scroll

                         +-0-+     +-0-+
>>-aListControl~Scroll(--+---+--,--+---+--)--------------------><
                         +-x-+     +-y-+


The Scroll method scrolls the content of a list view control.

Arguments:

The arguments are:

x

An integer value specifying the amount of horizontal scrolling. If the control is in icon, small-icon, or report view, this value specifies the number of pixels to be scrolled. If it is in list view, this value specifies the number of columns to be scrolled. The default value is 0.

y

An integer value specifying the amount of vertical scrolling. If the control is in icon, small-icon, or report view, this value specifies the number of pixels to be scrolled. If it is in list view, this value specifies the number of lines to be scrolled. The default value is 0.

Return value:

0

Scrolling was successful.

1

Scrolling failed.

BkColor

>>-aListControl~BkColor----------------------------------------><


The BkColor method retrieves the background color for a list view control.

Return value:

The color-palette index specifier (0 to 18). For more information on color palettes, refer to Definition of Terms.

BkColor=

>>-aListControl~BkColor=(--color--)----------------------------><


The BkColor= method sets the background color of a list view control.

Arguments:

The only argument is:

color

The new background color. Specify the color-palette index specifier (0 to 18). For more information on color palettes, refer to Definition of Terms.

Example:

The following example sets the background color of a list control to yellow:

::method Yellow
  curList = self~GetListControl(104)
  curList~BkColor = 15
  curList~Update

TextColor

>>-aListControl~TextColor--------------------------------------><


The TextColor method retrieves the text color of a list view control.

Return value:

The color-palette index specifier (0 to 18). For more information on color palettes, refer to Definition of Terms.

TextColor=

>>-aListControl~TextColor=(--color--)--------------------------><


The TextColor= method sets the text color of a list view control.

Arguments:

The only argument is:

color

The new text color. Specify the color-palette index specifier (0 to 18). For more information on color palettes, refer to Definition of Terms.

Example:

The following example sets the text color of a list control to light blue:

::method LightBlue
  curList = self~GetListControl(104)
  curList~BkColor = 9
  curList~Update

TextBkColor

>>-aListControl~TextBkColor------------------------------------><


The TextBkColor method retrieves the background color of the text in a list view control.

Return value:

The color-palette index specifier (0 to 18). For more information on color palettes, refer to Definition of Terms.

TextBkColor=

>>-aListControl~TextBkColor=(--color--)------------------------><


The TextBkColor= method sets the background color for the text in a list view control.

Arguments:

The only argument is:

color

The new background color for text. Specify the color-palette index specifier (0 to 18). For more information on color palettes, refer to Definition of Terms.