keyTMS ALL-ACCESS
local_offerOne money and time saving bundle
mouseCross Platform UI
bar_chartReporting
languageWeb
swap_horizCommunication
storageData
mouseWindows UI
  •  
  •  
  •  
  1. Home
  2. Products
  3. VCL Components
  4. TSectionListBox
  5. Documentation

TSectionListBox documentation

Extra

For HTML formatting capabilities, check the mini HTML documentation

Procedures

procedure ExpandAll;
expands all sections

procedure ContractAll;
contracts all sections

function GetActiveSection:TListSection;
returns the section that has focus or of which on of the items has focus

function FocusSection(section:TListSection);
if a section is invisible due to scrollbars, this method scrolls the section in view

function GetItemSection(index:integer):TListSection;
returns the section that contains the item Index in the listbox

function GetItemSectionIndex(index:integer):integer;
returns the index of the section in the Sections property to which the Item Index in the listbox belongs

function GetSectionSubItem(sectionidx,subitemidx:integer):string;
returns the item in the section indicated by SectionIdx at subitem position SubItemIdx

function GetRichSectionSubItem(sectionidx,subitemidx:integer):string;
returns the item in the section indicated by SectionIdx at subitem position SubItemIdx as full RTF string

function IsSection(idx:integer):boolean;
Indicates whether the item in the list idx is a section or a subitem

function GetSectionListIndex(sectionidx:integer):integer;
Gets the index in the listbox of the section. This index will differ depending on the contract/expand state of the previous sections

function SetSelection(sectionidx,subitemidx:integer):boolean;
Sets the selected item to sectionidx,subitemidx. If subitemidx is contained in a contracted section, the section is expanded Returns false if sectionidx/subitemidx does not exist

function GetSelection(var SectionIdx,SubItemIdx:integer;var SelString:string):boolean;
Returns the current selected item. If no item is selected, the method returns false.

procedure SaveToFile(filename:string);
Saves the contents of the SectionList to a file

procedure LoadFromFile(filename:string);
Loads the contents of the SectionList from a file

procedure SaveToInifile(filename:string);
Saves the contents of the SectionList to an INI file. Section captions contains the INI file section text, subitems contain Key=Value

procedure LoadFromInifile(filename:string);
Loads the contents of the SectionList from an INI file. Section captions contains the INI file section text, subitems contain Key=Value

procedure OptimizeTabs(padding:integer);
Fills the TabPosition collection with values optimized depending on the items in the sections. Tabs are set to let fix space padding between text.

function RichToString(richeditor:trichedit):string;
Result is the full RTF text from the richedit control. Can be used with the internal SectionListBox richedit control (exposed by RichEdit property)

procedure StringToRich(s:string;richeditor:trichedit);
Puts the RTF string into the richeditor. Can be used with the internal SectionListBox richedit control (exposed by RichEdit property)

Rich text formatting example : Adds a new section with a subitem in rich text

with SectionListBox.Sections.Add do
begin
 caption:='Rich text';
 //construct the rich text to add in the internal rich edit control
 with SectionListBox.richedit do
  begin
   text:='This is some rich text here';
   selstart:=0;
   sellength:=4;
   selattributes.style:=[fsBold];
   selstart:=13;
   sellength:=9;
   selattributes.style:=[fsBold];
   selattributes.color:=clred;
  end;
  //move full RTF text of rich edit control to the subitem of the section
  s:=RichToString(RichEdit);
  SubItems.Add(s);
 end;

procedure SortAllSubItems;
Sorts all SubItems of all Sections. If no specific sorting for a Section is specified, sorting is ascending. Otherwise, sorting is based of the section SortDirection property.

procedure SortAllSections;
Sorts the sections based on the Section caption. Sorting is ascending

procedure SortAll;
Sorts Sections as well as its SubItems.

procedure BeginUpdate;
Disables screen updates. Use this method before lengthy insert operations. Updates are displayed after calling EndUpdate.

procedure EndUpdate;
Enables screen updates again, showing all changes since the first BeginUpdate call.

Properties

property ScrollType:TScrollType;
Determines the type of scrollbars used. Can be either slsNormal, slsFlat or slsEncarta. This property has effect only when ScrollProportional is true.

property ScrollWidth:integer;
Determines the width of the scrollbars. This property has only effect for flat or encarta style scrollbar.

property ScrollColor:TColor;
Determines the background color of the scrollbars. This property has effect only when scrollbar is flat or encarta style . The default color is clNone.

property ScrollTrack:boolean;
Determines if the list content is scrolled while tracking or not. The default color is true.

property SectionHeight:integer;
Height of the sections.

property SectionFont:tFont;
Font used to draw sections

property SectionColor:tColor;
Determines the background color of the sections

property SectionIndent:integer;
Indent of the section text from left

property SectionImages:TImageList;
Imagelist holding the images to draw in the section

property SelectionColor:tColor;
Determines the background color of the selection item

property SelectionTextColor:tColor;
Determines the text color of the selected item

property SubItemImages:TImageList;
Imagelist holding the images to draw in the section subitems

property SubItemIndent:integer;
Indent of the subitem text

property URLSettings:tURLSettings;
Determines if subitem text should be URL aware and how to display URLs.

Subproperties :
property URLAware:boolean; : if true, puts the SectionListbox in URL aware mode;
property URLColor:TColor : color used to display URLs;
property URLFull:boolean : if true, draws the URL specifiers http://, ftp://, file:// as well;

property ExpandGlyph:tbitmap;
Glyph used to mark a section in the expanded state

property ContractGlyph:tbitmap;
Glyph used to mark a section in the contracted state

property ContractDisable:boolean;
Disables runtime section contracting

property ExpandDisable:boolean;
Disables runtime section expanding

property ActiveSection:TActiveSection;
Determines which part of the section is used to act as a expand or contract click. This can be the node only or the full section. TActiveSection = (asFull, asNodeOnly);

property NodeType:TListNodeType;
Specifies which type of expand/contract node to use. This can be flat crossed rectangle style, 3D style or use expand/contract glyphs.
TListNodeType = (lnFlat,ln3D,lnGlyph);

property SectionFocus:TSectionFocus;
Specifies which focus style to use. This can be classic dashed line focus or 3D focus effect.

TSectionFocus = (sfDash,sf3D);

property TabPositions:tTabPositionCollection;
The TabPositions property is a collection of integer values that indicate the position of the tabs in the listbox. The tabs can be right or left aligned. Tabs must be organized in increasing order (except for sign) Ie. 100,200,300 is a valid tab setting first left aligned tab at : 100; TabType=tableft second right aligned tab at : 200, TabType=tabright third left aligned tab at : 300, TabType=tableft

property TabPosMove:boolean;
If true, the TabPositions can be set with the mouse at runtime

property ImageSpacing:smallint;
if sectionimages or subitemimages are used, this parameter determines the spacing between the image and the text

property FullFocus:boolean;
if true, a focused item is shown in full sectionlistbox width, if false, only text is highlighted.

property Wallpaper:TBitmap;
This specifies the listbox background bitmap. For optimized drawing, choose a bitmap with height equal to subitemheight.

property WordWrap:boolean;
If true, subitems are displayed in wordwrap mode

property OneExpanded:boolean;
If true, only one section can be expanded at a time

property Sections : TSectionListCollection;
collection holding all the sections of type TListSection :

with ListSection :

TListSection = class(TCollectionItem)
public
property SubItemImageIdx[i:integer]:smallint; : index of the subitemimage
property SubItemCheckState[i:integer]:boolean; : state of the checkbox if ControlType = scCheckBox
published
property Alignment:TAlignment; : left, right, centered justification
property AutoEdit:boolean; if true and ReadOnly is false, the inplace editor is automatically focussed on expand
property Caption:string; : section text
property Fixed:boolean; : if true, section can not be expanded, collapsed by mouse click
property ImageIndex:integer; : index of the section image in the SectionImages list
property State:tListSectionState; : lssExpanded or lssContracted state of the section
property SubItems:tstrings; : stringlist of the section subitems
property Color:tColor; : background color of the section
property Lines:TSectionLines; : style of lines : TSectionLines = (slNone,slVertical,slHorizontal,slBoth);
property Font:tFont; : Font used for the section.
property FontUsage:tFontUsage; : Determines if the section, subitems or both should use the Font property. TFontUsage = (fuSubItems,fuSection,fuBoth);
property EndEllipsis:boolean; : If true, draws ellipsis if text cannot fit in the listbox
property ControlType:TSectionControlType; : Can be scCheckBox, scRadioButton, scText
property ItemHeight: set the height of the subitems independent for each section
property RadioIndex:integer; : index of selected radiobutton in scRadioButton control type
property SortShow:boolean : shows the sort direction indicator when true
property SortDirection: default sdNone. Set to sdAscending to sort ascending, sdDescending to sort descending
property Tag: integer; general purpose tag property
property OwnerDraw: boolean; The OnDrawItem event is called for the subitems in this section if true.
property ReadOnly: boolean; true if inplace editing is not allowed
property VAlignment: TValignment; vertical alignment of the section
end;

Example of adding sections programmatically :

var
ls:TListSection;

begin
 with SectionListbox.Sections.Add do
 begin
  Caption:='Test';
  SubItems.Add('One');
  SubItems.Add('Two');
  SubItems.Add('Three');
  State:=lssExpanded;
 end;
end;

At runtime in C++Builder :

{
TListSection *ls;
ls = SectionListBox->Sections->Add();
ls->Caption = "Test";
ls->SubItems->Add("One");
ls->SubItems->Add("Two");
ls->SubItems->Add("Three");
ls->State = lssContracted;
}

Events

property OnChange:TSubItemClickEvent;
event fired when selection changes in the SectionListBox.
TSubItemClickEvent = procedure(Sender:TObject;sectionidx,subitemidx:integer);
Sectionidx indicates the section in which is the current selected item is.
SubItemidx is the zero based index of the item in the section. If the section header is clicked, it is -1

property OnExpandSection:TExpandSectionEvent;
event fired when the user expands a section

property OnContractSection:TContractSectionEvent;
event fired when the user contracts a section

property OnSubItemClick:TSubItemClickEvent;
event fired when the user clicks a subitem

property OnSubItemRClick:TSubItemClickEvent;
event fired when the user rightclicks a subitem

property OnSubItemDblClk:TSubItemClickEvent;
event fired when the user doubleclicks a subitem

property OnSubItemRDblClk:TSubItemClickEvent;
event fired when the user right doubleclicks a subitem

property OnInsertSubItem:TInsertSubItemEvent;
if the event is assigned, the user can insert new subitems with the INS button. With this event,the subitem text for the new subitem can be set.

property OnDeleteSubItem:TDeleteSubItemEvent;
if the event is assigned, the user can delete subitems with the DEL button.

property OnInsertSection:TInsertSectionEvent;
if the event is assigned, the user can insert new sections with the INS button. With this event,the subitem text for the new section as well as its subitems can be set.

property OnDeleteSection:TDeleteSectionEvent;
if the event is assigned, the user can delete sections with the DEL button.

property OnDrawitem:TDrawItemEvent;
Called when the OwnerDraw property is true for a section.
TDrawItemEvent = procedure(Sender:TObject; section:TListSection ;sectionidx, subitemidx:integer;canvas:tcanvas; arect:trect; astate:TOwnerDrawState)

property OnStartEdit:TEditEvent;
Called when inplace editing starts

property OnEndEdit:TEditEvent;
Called when inplace editing ends

property OnCheckBoxClick:TSubItemClickEvent;
Called when a checkbox changes state

property OnRadioClick:TSubItemClickEvent;
Called when the section radiobuttons change state