PureLVSORT library

Overview

Automatically sorts listicon gadgets after a LVN_COLUMNCLICK event (click on column header) or a PureLVSORT_SortListIconNow() function call.

And some other usefull ListIconGadget functions.

Functions

PureLVSORT_SelectGadgetToSort(GadgetNumber.l, ShowClickedHeader.l)

Select new ListIconGadget to sort.

ShowClickedHeader :

    #PureLVSORT_ShowClickedHeader_No		--> don't modify the clicked header
    #PureLVSORT_ShowClickedHeader_Text	--> clicked header is modified like "« HEADER »" / "» HEADER «"
						according to sorting direction :    +1      /     -1
    #PureLVSORT_ShowClickedHeader_IconLeft	--> clicked header is modified like "^ HEADER"   /  "v HEADER" (where ^ and v are icons)
						according to sorting direction :    +1      /     -1
    #PureLVSORT_ShowClickedHeader_IconRight	--> clicked header is modified like "HEADER ^"   /  "HEADER v" (where ^ and v are icons)
						according to sorting direction :    +1      /     -1

Return codes :

  #PureLVSORT_Ok			; Success
  #PureLVSORT_NotAGadget		; Specified gadget does not exist
  #PureLVSORT_MemoryAllocationProblem	; Memory allocation failed
  #PureLVSORT_UndefinedGadget	; Specified gadget was not initialized with PureLVSORT_SelectGadgetToSort()

PureLVSORT_ClearGadget(GadgetNumber.l)

Don't sort ListIconGadget anymore (if click on column header).

PureLVSORT_DefineAlphabeticOrder(*UserArray)

Set alphabetic order for column type #PureLVSORT_Alphabetic_User.

*UserArray is a pointer to a 256 bytes array, defining the sorting order for the 256 ASCII codes.
Byte 0 : sorting order for ASCII code 0, ..., byte 65 : sorting order for ASCII code 65 "A", ..., byte 255 : sorting order for ASCII code 255.

Warning : this function must be called before setting a #PureLVSORT_Alphabetic_User column type.

PureLVSORT_DefineUserCallback(*UserCallbackAddress)

Define user sorting callback for column type #PureLVSORT_UserCallback.

The callback is a procedure called when a ListIconGadget is sorted.

The callback procedure is like this :

Procedure MySortingCallback(ListIconNumber.l, ListIconColumn.l, Item1.s, Item2.s)
 ;
 Compare Item1 and Item2 and
  Return 1 if Item1 > Item2
  Return -1 if Item1 < Item2
  Return 0 if Item1 = Item2
 ;
EndProcedure

declared like that :

PureLVSORT_DefineUserCallback(@MySortingCallback())

where :

ListIconNumber is the purebasic gadget ID
ListIconColumn is the sorted column
Item1 and Item2 are the items to sort.

Warning : this function must be called before setting a #PureLVSORT_UserCallback column type.

PureLVSORT_DefineFilterCallback(*UserCallbackAddress)

Define user filtering callback for #HDN_FILTERCHANGE or #HDN_FILTERBTNCLICK events.

The callback is a procedure called when a listicon header filter changes (#HDN_FILTERCHANGE) or a header button is pressed (#HDN_FILTERBTNCLICK).
The filter mode is activated with the PureLVSORT_SetFilter() function.

The callback procedure is like this :

Procedure MyFilterCallback(GadgetNumber.l, FilterString.s, ListIconColumn.l, EventID.l)
  ; ...
EndProcedure

declared like that :

PureLVSORT_DefineFilterCallback(@MyFilterCallback())

where :

GadgetNumber is the purebasic gadget ID
FilterString is the header filter text
ListIconColumn is the header column
EventID is the trigger event (#PureLVSORT_FilterBtnClick or #PureLVSORT_FilterChange)

PureLVSORT_CountColumns(GadgetNumber.l)

Count the columns in a ListIcon.

Returns -1 if failed.

PureLVSORT_SetColumnType(GadgetNumber.l, Column.l, ColumnType.b)

Set column type.

ColumnType :

        #PureLVSORT_String [DEFAULT] 		; example : "ABCDE" (case insensitive)
        #PureLVSORT_String_CaseSensitive		; example : "aDECd"
        #PureLVSORT_Numeric			; example : "-1523"
        #PureLVSORT_Float			; example : "0.250"
        #PureLVSORT_DateDDMMYYYY		; example : "31/12/2003"
        #PureLVSORT_DateMMDDYYYY		; example : "12/31/2003"
        #PureLVSORT_DateDDMMYYYYHHMMSS	; example : "31/12/2003 12:31:21"
        #PureLVSORT_DateDDMMYYHHMM		; example : "31/12/03 12:31"
        #PureLVSORT_FileSize			; examples : "1.23 GB", "235.51 MB", "1021 KB"
        #PureLVSORT_NoSorting			; column is locked (no sorting after a LVN_COLUMNCLICK event)
        #PureLVSORT_Alphabetic_User		; sorting order is defined by a user byte array  [PureLVSORT_DefineAlphabeticOrder()]
        #PureLVSORT_UserCallback		; sorting order is defined by a user callback  [PureLVSORT_DefineUserCallback()]
                 
Initialize gadget with PureLVSORT_SelectGadgetToSort().

PureLVSORT_SetColumnAlignment(GadgetNumber.l, Column.l, Alignment.l)

Specifies the alignment of the column heading and the subitem text in the column.

Possible values :
#PureLVSORT_Center	Text is centered;
#PureLVSORT_Left	   	Text is left-aligned;
#PureLVSORT_Right		Text is right-aligned.

PureLVSORT_SetColumnWidth(GadgetNumber.l, Column.l, width.l)

Set ListIcon column width in list view coordinates, or one of the following values :
#PureLVSORT_AutoSize	Automatically sizes the column;
#PureLVSORT_UseHeader	Automatically sizes the column to fit the header text.

PureLVSORT_SetLastColumnAutoResize(GadgetNumber.l, TrueOrFalse.l)

Resize the last column when the ListIcon is resized.

PureLVSORT_SetUserIcons(IconArrowUpHandle.l, IconArrowDownHandle.l)

Define user icons [bitmap handles]

PureLVSORT_SortListIconNow(ListIconGadget.l, ListIconColumn.l, SortDirection.l)

This function simulates a LVN_COLUMNCLICK event for the specified gadget
SortDirection : +1 / -1
Initialize gadget with PureLVSORT_SelectGadgetToSort().

PureLVSORT_ScrollToRow(GadgetNumber.l, Row.l)

Scroll the ListiconGadget to the given row (make it visible at the top of the list).

PureLVSORT_GetClickedColumn(GadgetNumber.l)

Get last clicked column number for the gadget.

Returns -1 if no column was clicked.

PureLVSORT_GetClickedCellColumn()

Get the listicon clicked cell column after a click event.

Events
#PB_EventType_LeftClick
#PB_EventType_LeftDoubleClick
#PB_EventType_RightClick
#PB_EventType_RightDoubleClick

Returned values
- Column [>= 0]
- Error : empty column [-1]

PureLVSORT_GetClickedCellRow()

Get the listicon clicked cell row after a click event.

Events
#PB_EventType_LeftClick
#PB_EventType_LeftDoubleClick
#PB_EventType_RightClick
#PB_EventType_RightDoubleClick

Returned values
- Row [>= 0]
- Error : empty row [-1]

PureLVSORT_GetSortingDirection(GadgetNumber.l)

Get last clicked column sorting direction for the gadget.

Returns +1/-1, or 0 if no column was clicked.

PureLVSORT_LoadListIcon(GadgetNumber.l, Filename.s)

Load ListIcon content saved with PureLVSORT_SaveListIcon().

Returns #False if failed.

PureLVSORT_LoadListIconTXT(GadgetNumber.l, Filename.s)

Load ListIcon content from a text file (saved with PureLVSORT_SaveListIconTXT()).

Returns #False if failed.

PureLVSORT_LoadListIconFromMem(GadgetNumber.l, *Buffer, FilterString.s, FilterColumn.l, CaseInsensitive.l)

Load ListIcon items from memory with a filter.
If FilterString = "", all items are loaded.

Returns #False if failed.

The items must have been saved with the PureLVSORT_SaveListIconToMem() function.
It's a very usefull function for filtering ; see example below :

PureLVSORT_SaveListIcon(GadgetNumber.l, Filename.s)

Save ListIcon content to a file (compressed with JCalG1 algorithm).

Returns #False if failed.

PureLVSORT_SaveListIconTXT(GadgetNumber.l, Filename.s)

Save ListIcon content to a text file (column separator is TAB [chr(9)]).

Returns #False if failed.

PureLVSORT_SaveListIconToMem(GadgetNumber.l)

Save the ListIcon items to memory.

Returns the memory address or #False if failed.

It's the programmer's responsability to release the memory.
It's a very usefull function for filtering ; see the PureLVSORT_LoadListIconFromMem() function for more details

PureLVSORT_SetFilter(GadgetNumber.l)

Enables a filterbar as part of the standard header for the ListIcon.

If a cell content matches with the entered filterbar value (in the same column), the
library will select the corresponding line and ensure it is visible.

Initialize gadget with PureLVSORT_SelectGadgetToSort().

Note
There are some cosmetic glitches if the sorting icons are activated at the same time
(options #PureLVSORT_ShowClickedHeader_IconLeft/Right).
If this is inacceptable, you can use #PureLVSORT_ShowClickedHeader_No/Text
before activating the filterbar and restore the icons when disabling the filterbar.

PureLVSORT_SetFilterTimeOut(FilterTimeOut)

Set filter change timeout in ms [default is 1000].

Must be called before PureLVSORT_SetFilter().

PureLVSORT_ResetFilter(GadgetNumber.l)

Disables the filterbar in the ListIcon header.

PureLVSORT_SetFilterString(GadgetNumber.l, Column.l, FilterString.s)

Set filter the string for a ListIcon column.

The filter mode is activated with the PureLVSORT_SetFilter() function.

PureLVSORT_GetFilterString(GadgetNumber.l, Column.l)

Get the filter string for a ListIcon column.

The filter mode is activated with the PureLVSORT_SetFilter() function.

PureLVSORT_SetColumnFlag(GadgetNumber.l, Column.l, ColumnFlag.b)

Set a column flag.

Flags :
#PureLVSORT_Column_Fixed : the column width is fixed
#PureLVSORT_Column_Hidden : the column is hidden

Initialize gadget with PureLVSORT_SelectGadgetToSort().

PureLVSORT_ResetColumnFlag(GadgetNumber.l, Column.l, ColumnFlag.b)

Reset a column flag set with PureLVSORT_SetColumnFlag().

Flags :
#PureLVSORT_Column_Fixed
#PureLVSORT_Column_Hidden