AddItem

Adds an item to a list control or object.

To add an item to

Use

A ListBox or DropDownListBox control

Syntax 1

A PictureListBox, DropDownPictureListBox, and RibbonComboBoxItem control

Syntax 2

A ListView control when you only need to specify the item name and picture index

Syntax 3

A ListView control when you need to specify all the properties for the item

Syntax 4

A PDFTableOfContents and PDFTableOfContentsItem objects Syntax 5

Syntax 1: For ListBox and DropDownListBox controls

Description

Adds a new item to the list of values in a list box.

Applies to

ListBox and DropDownListBox controls

Syntax

listboxname.AddItem ( item )

Argument

Description

listboxname

The name of the ListBox or DropDownListBox in which you want to add an item

item

A string whose value is the text of the item you want to add


Return value

Integer.

Returns the position of the new item. If the list is sorted, the position returned is the position of the item after the list is sorted. Returns -1 if it fails. If any argument's value is null, AddItem returns null.

Usage

If the ListBox already contains items, AddItem adds the new item to the end of the list. If the list is sorted (its Sorted property is true), PowerBuilder re-sorts the list after the item is added.

A list can have duplicate items. Items in the list are tracked by their position in the list, not their text.

AddItem and InsertItem do not update the Items property array. You can use FindItem to find items added at runtime.

Adding many items to a list with a horizontal scroll bar

If a ListBox or the ListBox portion of a DropDownListBox will have a large number of items and you want to display an HScrollBar, call the SetRedraw function to turn Redraw off, add the items, call SetRedraw again to set Redraw on, and then set the HScrollBar property to true. Otherwise, it may take longer than expected to add the items.

Examples

This example adds the item Edit File to the ListBox lb_Actions:

integer rownbr
string s
 
s = "Edit File"
rownbr = lb_Actions.AddItem(s)

If lb_Actions contains Add and Run and the Sorted property is false, the statement above returns 3 (because Edit File becomes the third and last item). If the Sorted property is true, the statement above returns 2 (because Edit File becomes the second item after the list is sorted alphabetically).

See also

DeleteItem

FindItem

InsertItem

Reset

TotalItems

Syntax 2: For PictureListBox, DropDownPictureListBox, and RibbonComboBoxItem controls

Description

Adds a new item to the list of values in a picture list box.

Applies to

PictureListBox, DropDownPictureListBox, and RibbonComboBoxItem controls

Syntax

listboxname.AddItem ( item {, pictureindex } )

Argument

Description

listboxname

The name of the PictureListBox or DropDownPictureListBox or RibbonComboBoxItem in which you want to add an item

item

A string whose value is the text of the item you want to add

pictureindex (optional)

An integer specifying the index of the picture you want to associate with the newly added item


Return value

Integer.

Returns the position of the new item. If the list is sorted, the position returned is the position of the item after the list is sorted. Returns -1 if it fails. If any argument's value is null, AddItem returns null.

Usage

If you do not specify a picture index, the newly added item will not have a picture.

If you specify a picture index that does not exist, that number is still stored with the picture. If you add pictures to the picture array so that the index becomes valid, the item will then show the corresponding picture.

For additional notes about items in list boxes, see Syntax 1.

Example 1

This example adds the item Cardinal to the PictureListBox plb_birds:

integer li_pic, li_position
string ls_name, ls_pic

li_pic = plb_birds.AddPicture("c:\pics\cardinal.bmp")
ls_name = "Cardinal"
li_position = plb_birds.AddItem(ls_name, li_pic)

If plb_birds contains Robin and Swallow and the Sorted property is false, the AddItem function above returns 3 because Cardinal becomes the third and last item. If the Sorted property is true, AddItem returns 1 because Cardinal is first when the list is sorted alphabetically.

Example 2

This example adds two items to the ribbon combo box:

Integer li_Return
RibbonComboBoxItem lr_ComboBox

li_Return = lr_ComboBox.SetBoxPictureList("PaperSizeA0Small!,PaperSizeA1Small!")
li_Return = lr_ComboBox.AddItem("Item1")
li_Return = lr_ComboBox.AddItem("Item2",1)

See also

DeleteItem

FindItem

InsertItem

Reset

TotalItems

Syntax 3: For ListView controls

Description

Adds an item to a ListView control.

Applies to

ListView controls

Syntax

listviewname.AddItem ( label, pictureindex )

Argument

Description

listviewname

The name of the ListView control to which you are adding a picture or item

label

The name of the item you are adding

pictureindex

The index of the picture you want to associate with the newly added item


Return value

Integer.

Returns the index of the item if it succeeds and -1 if an error occurs.

Usage

Use this syntax if you only need to specify the label and picture index of the item you are adding to the ListView. If you need to specify more than the label and picture index, use Syntax 4.

Examples

This example uses AddItem in the Constructor event to add three items to a ListView control:

lv_1.AddItem("Sanyo" , 1)
lv_1.AddItem("Onkyo" , 1)
lv_1.AddItem("Aiwa" , 1)

See also

DeleteItem

FindItem

InsertItem

Reset

TotalItems

Syntax 4: For ListView controls

Description

Adds an item to a ListView control by referencing all the attributes in the ListView item.

Applies to

ListView controls

Syntax

listviewname.AddItem ( item )

Argument

Description

listviewname

The name of the List View control to which you are adding a picture or item

item

The ListViewItem variable containing properties of the item you are adding


Return value

Integer.

Returns the index of the item if it succeeds and -1 if an error occurs.

Usage

Use this syntax if you need to specify all the properties for the item you want to add. If you only need to specify the label and picture index, use Syntax 3.

Examples

This example uses AddItem in a CommandButton Clicked event to add a ListView item for each click:

count = count + 1
listviewitem l_lvi
l_lvi.PictureIndex = 2
l_lvi.Label = "Item "+ string(count)
lv_1.AddItem(l_lvi)

See also

DeleteItem

FindItem

InsertItem

Reset

TotalItems

Syntax 5: For PDFTableOfContents and PDFTableOfContentsItem objects

Description

Adds a chapter to the table of contents.

Applies to

PDFTableOfContents objects

PDFTableOfContentsItem objects

Syntax

PDFTableOfContentsItem AddItem(PDFText chapterObject)
PDFTableOfContentsItem AddItem(PDFTextBlock chapterObject)

Argument

Description

chapterObject

The text or textblock (heading) to add for a chapter in the table of contents.


Return value

PDFTableOfContentsItem objects. Returns the table of contents item created in the table of contents if the function succeeds.

Usage

Use this syntax to add chapters to the table of contents. The AddItem function of PDFTableOfContents adds the level-1 chapters; and the AddItem function of PDFTableOfContents adds the sub-level chapters.

The chapterObject is added to both the table of contents, and to a PDFPage. Then, the chapterObject in the table of contents is linked to the actual chapter in the PDFPage.

Examples

This example adds level-1 and level-2 chapters to the table of contents and have them linking to the actual chapter in the document:

PDFDocument lpdf_doc
PDFpage lpdf_page,lpdf_page1
PDFmultilinetext lpdf_mtext
PDFtableofcontents lpdf_toc
PDFtableofcontentsitem lpdf_tocitem
PDFtext lpdf_title,lpdf_chapter,lpdf_chapteritem
PDFfont lpdf_font

string ls_ssText
integer li_fhandle
long ll_fileLen, ll_readSize

lpdf_doc = create PDFDocument
lpdf_page = create PDFpage
lpdf_page1 = create PDFpage
lpdf_mtext = create PDFmultilinetext
lpdf_toc =  create PDFtableofcontents
lpdf_title = create PDFtext
lpdf_chapter = create PDFtext
lpdf_font = create PDFfont

//Set the table of contents font
lpdf_font.fontname = "Microsoft YaHei"
lpdf_font.bold = true
lpdf_font.italic = true
lpdf_font.fontsize = 20
lpdf_toc.setfont( lpdf_font) 

lpdf_title.content = "Table of Content"
lpdf_title.font.fontsize = 36
lpdf_title.font.bold = true
lpdf_title.y = 20
lpdf_title.x = (lpdf_page.getwidth( )-lpdf_title.width)/2
//Set the table of contents title
lpdf_toc.settitle( lpdf_title)

lpdf_chapter.content = "chapter1"
lpdf_chapteritem = lpdf_chapter.clone( )
lpdf_chapteritem.content = "chapter1.1"

//Read file content
ll_fileLen = FileLength64("Testdocument.txt")
li_fhandle = fileopen("Testdocument.txt", textMode! )
blob readByte
ll_readSize = fileReadEx(li_fhandle, readByte,ll_fileLen)
ls_ssText = string(readByte)
fileclose(li_fhandle)

lpdf_mtext.width = lpdf_page.getwidth( )
lpdf_mtext.content = ls_ssText

//Add level-1 chapter heading to the table of contents
lpdf_tocitem = lpdf_toc.additem( lpdf_chapter)
//Add level-2 chapter heading to the table of contents
lpdf_tocitem.additem(lpdf_chapteritem )

lpdf_page.addcontent( lpdf_chapter)
lpdf_page.addcontent( lpdf_chapteritem)
lpdf_page.addcontent( lpdf_mtext)

lpdf_doc.addpage( lpdf_page)

//Set the table of contents margines
lpdf_toc.SetLeftMargin(100)
lpdf_toc.SetTopMargin(100)
lpdf_toc.SetRightMargin(100)
lpdf_toc.SetBottomMargin(100)

//PDFTableOfContentsStyle_Simple!             /*For example: title 1 */
// PDFTableOfContentsStyle_Classic!            /*For example: title.........1 */
lpdf_toc.setstyle( PDFTableOfContentsStyle_Simple!)

lpdf_doc.settableofcontents( lpdf_toc)
lpdf_doc.save( "D:\ tocitem.pdf")

See also

GetBottomMargin

GetChapterObject

GetChapterTitle

GetFont

GetItem

GetItemCount

GetLeftMargin

GetPosByPageIndex

GetRightMargin

GetStyle

GetTitle

GetTopMargin

RemoveAll

RemoveItem

SetBottomMargin

SetFont

SetLeftMargin

SetPosByPageIndex

SetRightMargin

SetStyle

SetTitle

SetTopMargin