listbrowser.gadget Reference¶
Comprehensive function reference for listbrowser.gadget, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/listbrowser).
This page documents 20 functions of listbrowser.gadget. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.
Function index¶
listbrowser_gc()AllocLBColumnInfoA()AllocListBrowserNodeA()FreeLBColumnInfo()FreeListBrowserList()FreeListBrowserNode()GetLBColumnInfoAttrsA()GetListBrowserNodeAttrsA()HideAllListBrowserChildren()HideListBrowserNodeChildren()LBM_ADDNODE()LBM_EDITNODE()LBM_REMNODE()LISTBROWSER_GetClass()ListBrowserClearAll()ListBrowserSelectAll()SetLBColumnInfoAttrsA()SetListBrowserNodeAttrsA()ShowAllListBrowserChildren()ShowListBrowserNodeChildren()
listbrowser_gc()¶
**listbrowser_gc -- For browsing linked lists in various ways.
SUPERCLASS
gadgetclass
DESCRIPTION
This gadget is very similar to the LISTVIEW_KIND gadget in
gadtools.library, with numerous enhancements. It displays a list in
a scrolling view so that you can browse through it an select items
in various ways.
Advantages that this class provides:
> Allows the user to select multiple items (either by dragging or
shift-key selection).
> Displays items in multiple columns.
> Displays items as a mixture of text and images in different.
colours.
> Items can have checkboxes that can be toggled on and off.
> Text items can be edited in place.
> Hierarchical display of items supported.
> Can displays column headers.
> Allows allows horizontal scrolling of the list.
> Supports window relativity.
> Supports OS 3.0 BOOPSI Gadget HelpTest.
> Supports layout.gadget/window.class backfills.
METHODS
OM_NEW -- Create the list browser gadget. Passed to superclass then
calls OM_SET.
OM_SET -- Set object attributes. Passed to superclass first.
OM_DISPOSE -- Frees up the list browser gadget.
OM_UPDATE -- Set object notification attributes. Passed to
superclass first.
GM_RENDER -- Renders the gadget imagery. Overrides the superclass.
GM_GOACTIVE -- Handles activation, and selection of the scrollbars
and arrows. Overrides the superclass.
GM_HANDLEINPUT -- Handles input events once active. Overrides the
superclass.
GM_GOINACTIVE -- Closes the chooser menu. Overrides the superclass.
LBM_ADDNODE -- Adds a node to the attached list.
LBM_EDITNODE -- Edit an attached nodes attributes.
LBM_REMNODE -- Removes a node from the attached list.
LBM_SORT -- Sort attached list on specified column (V42)
LBM_SHOWCHILDREN -- (V42)
LBM_HIDECHILDREN -- (V42)
All other methods are passed to the superclass.
ATTRIBUTES
GA_Disabled (BOOL)
Set to TRUE to disable gadget, FALSE otherwise.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET, OM_GET)
GA_ReadOnly (BOOL)
Specifies that the list browser be read-only. This means that
no nodes within the list can be selected, the user can just
scroll through and view the list. The frame of the list will be
rendered as recessed as a visual cue that no nodes can be
selected.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET, OM_GET)
GA_TextAttr (struct TextAttr *)
Font to use for the contents of the list browser.
Defaults to the screen's font.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_Top (LONG)
Sets the node that is to appear at the top of list browser view.
Must be positive. If it is beyond the maximum possible value,
the last page in the list will be displayed.
NOTE: Before V45 this tag only worked AFTER rendering the gadget.
A workaround has been added in V45.
Defauts to 0.
Applicability is (OM_NEW, OM_SET, OM_GET, OM_NOTIFY)
LISTBROWSER_MakeVisible (LONG)
Ensures that the specified node is within the view and will
scroll only when necessary (unlike LISTBROWSER_Top which will
always scroll).
NOTE: Before V45 this tag only worked AFTER rendering the gadget.
A workaround has been added in V45.
Defaults to 0.
Applicability is (OM_NEW, OM_SET)
LISTBROWSER_Labels (struct List *)
An Exec list. Nodes in this list must be allocated with
AllocListBrowserNodeA().
A value of ~0 or NULL indicates that the list is "detached".
This must be done before you can modify a list already attached
to a list browser. After detaching, you should carry out your
updates to the list as quickly as possibly and then re-attach.
When a list browser is initially added to a window it MUST have
a list attached to it, ~0 is not valid in this case.
If you are using the LISTBROWSER_AutoFit attribute, the column
sizes will NOT be re-calculated when you change lists, you must
pass LISTBROWSER_AutoFit, TRUE again to adjust the column sizes
to fit your new list.
Note that when changing lists, you may want to reset certain
other attributes, such as LISTBROWSER_Selected, as this value
will be retained even when changing lists.
NOTE: Lists can NOT be shared amongst other list browsers
simultaneously.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_Spacing (WORD)
If you would like additional spacing between nodes in your
ListBrowser, use this tag to define how many extra pixels you
want.
Defaults to 0.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_Selected (LONG)
Sets the node in a single-select list that will be selected.
Any previously selected node(s) will be deselected. Note
that a node can become selected without being visible. A
value of -1 ( (ULONG)~0 ) is used to say that no item is
selected. The results of this tag are undefined in a multi-
select list browser.
This value is returned in the IntuitMessage.Code field.
Defaults to -1.
Applicability is (OM_NEW, OM_SET, OM_GET, OM_NOTIFY)
LISTBROWSER_SelectedNode (struct Node *)
This is the same as LISTBROWSER_Selected, except that you refer
to a node by its actual node structure.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_MultiSelect (BOOL)
Puts the list browser into multi-select mode. In multi-select
mode the user can select several items from the list holding
down the shift key and click items to add them to the ones
selected. Nodes can be deselected by holding down the shift
key and clicking on selected
node.
Selected nodes will have the LBNA_Selected attribute set to
TRUE (see GetListBrowserNodeAttrs()).
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_PersistSelect (BOOL) (V42)
When the list browser is in multi-select mode, this flag changes
the selection behaviour so that shift does NOT have to be held
down to select multiple nodes
Please be aware that this is distinctly NON-STANDARD behaviour
and therefore should be used with extreme discretion. About
the only time this may be appropriate is when you are dealing
with long lists where users are typically having to select a
large number of nodes. Because there is no simple way to clear
all selections when in this, some method should exist in your
user interface for clearing all selections.
This has no meaning if the list browser is not in multi-select
mode.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_ShowSelected (BOOL)
Specifies that you want the selected item in a single-select
list browser to be remain visible after it is selected, until
another item is selected. This tag has undefined results in
a multi-select list browser.
Defaults to TRUE.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_NumSelected (LONG)
The number of items selected in a multi-select list browser.
This contains a meaningless value if your listbrowser is not
multi-select.
Applicability is (OM_GET)
LISTBROWSER_RelEvent (ULONG)
Describes the event that caused the gadget release of the list
browser. Currently defined events are:
LBRE_NORMAL - Normal selection of an item.
LBRE_HIDECHILDREN - The user tried to hide children in a
hierarchical listbrowser.
LBRE_SHOWCHILDREN - The user tried to show children in a
hierarchical listbrowser.
LBRE_EDIT - The contents of a node were edited.
LBRE_DOUBLECLICK - The node was double-clicked on.
Additional return values added with V42:
LBRE_CHECKED - A checkbox node was checked.
LBRE_UNCHECKED_ - A checkbox node was unchecked.
LBRE_TITLECLICK - A column's title was clicked.
LBRE_COLUMNADJUST - A column's separator was clicked/dragged.
If applicable it is LISTBROWSER_CursorNode that is being manipula
ted.
Applicability is (OM_GET)
LISTBROWSER_VertSeparators (BOOL)
LISTBROWSER_Separators (BOOL)
Specifies that bevelled lines be drawn as separators between
each column. Has no effect if the list only has one column.
Defaults to TRUE.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_HorizSeparators (BOOL) (V41)
Renders horizontal lines below each node. This is useful if your
listbrowser is very wide, and you want to make it easier for
users to follow the rows of data.
Defaults to FALSE.
Applicability is (OM_NEW, OM_GET, OM_SET)
LISTBROWSER_Borderless (BOOL)
Create a view without a border. Useful if you wish the list
browser to take up the entire window, and have an attached
scroller in the window border.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_ColumnInfo (struct ColumnInfo *)
Provides the column layout info for the list browser. This is
an array of struct ColumnInfo. The array must have one entry
per column, plus one terminating entry where the ci_Width field
is -1. Each field in an array entry is filled in as follows:
ci_Width (WORD)
This specifies the percentage of the view width you want the
column to be. If a virtual width is given, this will be a
percentage of that, otherwise it will be a percentage of the
actual gadget width. Since you are specifying a percentage,
the actual size of the column will automatically adjust as th
e virtual or actual width of the gadget changes.
ci_Title (STRPTR)
If you have specified LISTBROWSER_ColumnTitles, TRUE then
you MUST fill in the titles you wish to appear for each colum
n here.
ci_Flags (ULONG)
Flags for the column, suported by V42 and later only.
CIF_WEIGHTED -- weighted width column (default)
CIF_FIXED -- fixed pixel width specided in ci_Width.
CIF_DRAGGABLE -- separator is user draggable.
CIF_NOSEPARATORS -- no separator on this column.
CIF_SORTABLE -- column is sortable.
CIF_CENTER -- column title is centred. (V47)
CIF_RIGHT -- column title is right-justified. (V47)
Passing NULL for the ColumnInfo means that you want a single
column taking up the entire width of the gadget with no title.
NOTES: ColumnInfo can NOT be shared amongst other list browsers
simultaneously. While the ColumInfo is in use by list browser,
you may not modify it. If you wish to make any modifications
to it, then first detach the list, make your modifications then
re-attach the list AND give use LISTBROWSER_ColumnInfo tag
again. List browser may modify the contents of this structure.
Defaults to NULL.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_ColumnTitles (BOOL)
Show titles above each column.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_SortColumn (WORD)
The number of a column that you want to sort by. The column
must be LBCIA_Sortable as well. See the SetLBColumnInfoA()
function for more details.
Defaults to -1 (none).
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
LISTBROWSER_AutoFit (BOOL)
Informs the ListBrowser that you want your column widths
calculated automatically for you to best fit the items in the
list attached to it. This will make your gadget a virtual
width gadget, with the virtual width being the width needed to
fit all columns.
For this to work, you must still pass LISTBROWSER_ColumnInfo with
a ColumInfo structure that has entries for each column, as normal
. The only change being that the initial values of the ci_Width field will be ignored, and instead will be filled in by ListBrowser.
If you are using the LISTBROWSER_AutoFit attribute, the column
sizes will NOT be re-calculated when you change lists with
LISTBROWSER_Label, you must pass LISTBROWSER_AutoFit, TRUE again
to adjust the column sizes to fit your new list.
Note for V42, with autofit enabled, wordwrap columns presently
will NOT rewrap. This is an internal chicken and the egg issue.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_VirtualWidth (WORD)
Allows rendering beyond the right edge of the view area in the
gadget.
Defaults to 0.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_Left (WORD)
The left offset of the view. This is only useful in combination
with either LISTBROWSER_VirtualWidth or LISTBROWSER_AutoFit to
reveal horizontal parts of the view that might be hidden. The
offset is specified in terms of pixels.
Defaults to 0.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_VerticalProp (BOOL)
Creates a vertical scrollbar with arrows for scrolling up and
down through the list.
Defaults to TRUE.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_HorizontalProp (BOOL)
Creates a horizontal scrollbar with arrows for scrolling
sideways across the view. Not useful unless you've used
LISTBROWSER_VirtualWidth or LISTBROWSER_AutoFit since there
would be nothing horizontally hidden.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_VPropTotal
LISTBROWSER_VPropTop
LISTBROWSER_VPropVisible
LISTBROWSER_HPropTotal
LISTBROWSER_HPropTop
LISTBROWSER_HPropVisible
These tags are for getting the status of the two prop gadgets
for the listbrowser. These are read-only and are intended for
linking external prop gadgets to a listbrowser.
Applicability is:
LISTBROWSER_VPropTotal, LISTBROWSER_VPropVisible,
LISTBROWSER_HPropTotal, LISTBROWSER_HPropVisible:
(OM_GET, OM_NOTIFY)
LISTBROWSER_VPropTop, LISTBROWSER_HPropTop:
(OM_SET, OM_GET, OM_NOTIFY)
LISTBROWSER_Position (ULONG)
Alters the view position within the listbrowser gadget. See
the include file for possible positions. This tag exists mainly
to make complex keyboard controls simple.
Applicability is (OM_SET)
LISTBROWSER_MouseX (WORD)
LISTBROWSER_MouseY (WORD)
Returns the co-ordinates of the mouse within the gadgets box
when the mouse button was last released in the gadget.
Applicability is (OM_GET)
LISTBROWSER_ScrollRaster (BOOL)
When this option is set, ListBrowser will use ScrollRaster() for
extra fast scrolling. This option is safe to use if the gadget
will be in a Smart Refresh or Super Bitmap window.
If the gadget will be in a Simple Refresh window, you should be
aware of an Intuition bug that will cause layer damage to not
be updated properly. This problem only exists under V37 of
Intuition, as ListBrowser sets the GMORE_SCROLLRASTER flag which
causes proper updates in V39 and above. HOWEVER, if you are
using ScrollRaster() in a window that contains a ListBrowser,
you MUST check the version of Intuition and use
ScrollWindowRaster() instead if the version is 39 or higher!
Defaults to TRUE.
Applicability is (OM_NEW, OM_GET, OM_SET)
LISTBROWSER_Hierarchical (BOOL)
Puts the ListBrowser into hierarchical mode, where nodes can be
browsed in a hierarchically by "generation", and generations can
be hidden.
See the LBNA_Generation node tag.
Defaults to FALSE.
Applicability is (OM_NEW, OM_GET, OM_SET)
LISTBROWSER_ShowImage (struct Image *)
LISTBROWSER_HideImage (struct Image *)
LISTBROWSER_LeafImage (struct Image *)
You can replace the images for showing a generation, hiding a
generation and the leaf (no children) image with your own. If
you do not provide any of them, default images will be rendered
for you. Note that the default leaf image is currently blank.
Defaults to NULL.
Applicability is (OM_NEW, OM_GET, OM_SET)
LISTBROWSER_Editable (BOOL)
If you want to enable in place editing of selected node columns,
you must set this flag to TRUE. Note that
LISTBROWSER_ShowSelected must also be TRUE for node editing to
work properly.
Defaults to FALSE.
Applicability is (OM_NEW, OM_GET, OM_SET)
LISTBROWSER_EditNode (LONG)
The number of a node that you want to start editing. You must
also specify the column you want to edit with
LISTBROWSER_EditColumn, and then activate the gadget using
ActivateGadget() (or ActivateLayoutGadget() if the listbrowser
is being used with layout.gadget).
This tag will also make the given node the selected node.
Defaults to -1.
Applicability is (OM_NEW, OM_SET)
LISTBROWSER_EditColumn (WORD)
The number of a column that you want to start editing. You must
also specify the node number you want to edit with
LISTBROWSER_EditNode, and then activate the gadget using
ActivateGadget() (or ActivateLayoutGadget() if the listbrowser
is being used with layout.gadget).
Defaults to -1.
Applicability is (OM_NEW, OM_SET)
LISTBROWSER_EditTags (struct TagList *)
Tags that you want to be passed to the string gadget used when
editing gadget text. Though you could theoretically pass any
tags to the gadget, you should generally not pass tags that
affect the position of the gadget.
Defaults to NULL.
Applicability is (OM_NEW, OM_GET, OM_SET)
LISTBROWSER_RelColumn (WORD)
The column the mouse was over when the button is released. This
is most useful in a listbrowser with editable nodes in different
columns. By checking both this and LISTBROWSER_RelEvent on
gadget release, you can tell if a node was edited and what column
of that node was edited.
This will not contain valid data if the mouse button was
released over a read-only node or if your listbrowser is in read-
only mode.
Applicability is (OM_GET)
LISTBROWSER_CheckImage (struct Image *) (V41)
Provide a custom image for a checkbox node while that node is
in the checked state. A NULL image means that listbrowser
render some default imagery.
Defaults to NULL.
Applicability is (OM_NEW, OM_GET, OM_SET)
LISTBROWSER_UncheckedImage (struct Image *) (V41)
Provide a custom image for a checkbox node while that node is
in the unchecked state. A NULL image means that listbrowser
render some default imagery.
Defaults to NULL.
Applicability is (OM_NEW, OM_GET, OM_SET)
LISTBROWSER_TotalNodes (LONG) (V41)
Return the total number of nodes currently attached to the
listbrowser.
Applicability is (OM_GET)
LISTBROWSER_MinNodeSize (LONG) (V42)
Minimum Node size for MemPool optimization, useful when
coupled with LBNA_NodeSize and using the internal pool.
Applicability is (OM_NEW,OM_SET)
LISTBROWSER_TitleClickable (BOOL) (V42)
Enables column title bar clicking when TRUE.
Defaults to FALSE.
Applicability is (OM_NEW,OM_SET)
LISTBROWSER_MinVisible (LONG) (V42)
Minimum visible node count. This causes the
minimum domain to be large enough to hold the specified number
of nodes using the the estimated average node height.
Note *ESTIMATED*; this is not a guaranteed result. The result may
be slightly less or greater than specified, and potentially
a lot greater if other objects within the layout group cause the
listbrowser to layout larger than its minimum domain.
Applicability is (OM_NEW,OM_SET)
LISTBROWSER_CursorSelect (LOng) (V42)
Keyboard cursor chosen node number.
Defaults to 0.
Applicability is (OM_SET, OM_GET)
LISTBROWSER_CursorNode (struct Node *) (V42)
Keyboard cursor chosen node pointer.
Defaults to NULL.
Applicability is (OM_GET)
LISTBROWSER_FastRender (BOOL) (V42)
Enables use of mask planes on non-RTG screens.
Also turns off custom pen support.
The potential performance improvement with deep ECS or
AGA displays can be *HUGE* for complex multi-column lists.
Defaults to FALSE.
Applicability is (OM_NET, OM_SET)
LISTBROWSER_TotalVisibleNodes (LONG) (V42)
Total visible node count (estimated). Note: In a hierarchical bro
wser, this is the number of nodes not hidden. In a non-hierarchical one this tag equals LISTBROWSER_TotalNodes.
Defaults to 0.
Applicability is (OM_GET)
LISTBROWSER_WrapText (BOOL) (V42)
Enables word-wrapping of column nodes flagged for word wrap.
Wrapping is delimited by a space, '\n' newline, or '\t' tab.
Defaults to 0.
Applicability is (OM_NEW, OM_SET)
LISTBROWSER_AutoWheel (BOOL) (V47)
Whether the listbrowser should intercept and handle mouse wheel
movements that occur while the pointer is over the listbrowser.
Defaults to TRUE.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_StayActive (BOOL) (V47)
If set the listbrowser will not give up keyboard focus so easily.
Keyboard fccus allows the user to move a cursor around with curso
r keys. Spacebar acts as a click, and return acts as a double click .
In particular this means that when mouseclicked it will retain fo
cus.
This is the same behavior as when activated by tabcycle or
programatically ActivateGadget()/ActivateLayoutGadget()
With StayActive you will not get GADGETUP events so instead liste
n for updates on LISTBROWSER_CursorSelected and check LISTBROWSER_R elEvent
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET, OM_GET)
LISTBROWSER_Striping (uint32) (V53.18)
Enables striping effect which alternates background colors.
The effect may make it easier for users to search larger
data sets. Note that the striping effect overrides any other
background coloring.
Currently defined values include:
LBS_NONE - no striping effect
LBS_ROWS - rows are striped
Defaults to LBS_NONE.
Applicability is (OM_NEW, OM_SET, OM_UPDATE)**
See also
graphics.library/ScrollRaster(), intuition.library/ActivateGadget(),
intuition.library/ScrollWindowRaster(), layers.library,
layout.gadget/ActivateLayoutGadget()
Bugs
Versions 41.250 and below do not support LISTBROWSER_PersistSelect.
Versions 41.631 and below do not support LISTBROWSER_FastRender corre
ctly.
AllocLBColumnInfoA()¶
AllocLBColumnInfoA -- Allocate column info array.
Synopsis
struct ColumnInfo *AllocLBColumnInfoA(UWORD cols, struct TagItem *tag
s);
struct ColumnInfo *AllocLBColumnInfo(UWORD cols, Tag tag1, ...);
Function
Allocates a ColumnInfo array that can be passed to the list browser
via the LISTBROWSER_ColumnInfo tag. This is a future friendly way
of allocating and initializing the ColumnInfo array.
TAGS
See SetLBColumnInfoAttrsA() for the list of supported tags.
AllocLBColumnInfoA() supports the following additional tags:
LBCIA_MemPool (APTR)
Specifies a custom memory pool to allocate ColumnInfo structs
from. The pool should be allocated with AllocSysObject() using
the ASOT_MEMPOOL type.
Defaults to NULL (internal pool).
Inputs
cols - How many columns your ListBrowser has.
tags - A tag list of attributes to set.
RESULT
Returns a pointer to the ColumnInfo array or NULL on error.
See also
FreeLBColumnInfo(), GetLBColumnInfoAttrsA(), SetLBColumnInfoAttrsA()
Bugs
This function is not currently implemented.
AllocListBrowserNodeA()¶
AllocListBrowserNodeA -- Allocate a ListBrowser node.
Synopsis
struct Node * AllocListBrowserNode(UWORD, Tag, ...)
node = AllocListBrowserNode(columns, Tag, ...)
struct Node * AllocListBrowserNodeA(UWORD, struct TagItem *)
node = AllocListBrowserNodeA(columns, taglist)
Function
Allocates a node that can be added to the Exec linked list of
labels in the listbrowser. This is the only way to allocate a
node for this list, you cannot allocate nodes yourself because
the ListBrowser class uses a private node structure.
TAGS
See SetListBrowserNodeAttrsA() for the list of supported tags. In
addition, AllocListBrowserNodeA() supports the following additional
tags:
LBNA_NodeSize (ULONG) (V41)
The size in bytes of the public portion of the node structure that
should be allocated. Usually the default (sizeof(struct Node)) will
suffice, unless you wish to have a custom node structure embedded
within the ListBrowser node, in which case you'd provide the size
of that structure. Then the node returned can be treated as an
instance of your custom node structure.
Defaults to sizeof(struct Node).
Inputs
columns - How many columns your ListBrowser has.
taglist - Attributes for the node, passed onto
SetListBrowserNodeAttrsA().
RESULT
node - A node that can be added into the Exec list of labels for
a ListBrowser gadget.
See also
FreeListBrowserNode(), SetListBrowserNodeAttrsA()
FreeLBColumnInfo()¶
FreeLBColumnInfo -- Free a column info array.
Synopsis
VOID FreeLBColumnInfo(struct ColumnInfo *ci);
Function
Frees the ColumnInfo array allocated with AllocLBColumnInfoA().
Inputs
ci - Pointer to the ColumnInfo array to free.
Safe to call with a NULL pointer.
See also
AllocLBColumnInfoA()
FreeListBrowserList()¶
FreeListBrowserList -- Free a list of ListBrowser nodes.
Synopsis
VOID FreeListBrowserList(struct List *)
FreeListBrowserList(List)
Function
Frees a list of ListBrowser nodes allocated.
Inputs
list - The list of nodes to free.
Safe to call with a NULL pointer.
See also
FreeListBrowserNode()
FreeListBrowserNode()¶
FreeListBrowserNode -- Free a ListBrowser node.
Synopsis
VOID FreeListBrowserNode(struct Node *)
FreeListBrowserNode(node)
Function
Frees a ListBrowser node allocated with the AllocListBrowserNodeA()
function.
Inputs
node - Pointer to the node to free.
Safe to call with a NULL pointer. (V47)
See also
AllocListBrowserNodeA()
GetLBColumnInfoAttrsA()¶
GetLBColumnInfoAttrsA -- Get column info attributes.
Synopsis
LONG result = GetLBColumnInfoAttrsA(struct ColumnInfo *ci,
LONG result = GetLBColumnInfoAttrs(struct ColumnInfo *ci,
Tag tag1, ...);
struct TagItem *tags);
Function
Gets attributes for a ColumnInfo structure in a future
friendly manner.
TAGS
The following tags listed in SetLBColumnInfoAttrsA() are supported:
LBCIA_Column (WORD)
LBCIA_Title (CONST_STRPTR)
LBCIA_Weight (WORD)
LBCIA_Width (WORD)
LBCIA_Flags (ULONG)
LBCIA_SortDirection (ULONG)
LBCIA_UserData (APTR)
Inputs
ci - Pointer to ColumnInfo array to get the information from.
Safe to call with a NULL pointer.
tags - A tag list of attributes to get. Each ti_Tag is the
attribute to get and ti_Data is a pointer to a location
to copy the result into. Safe to call with a NULL pointer.
Results
result - The actual number of attributes retrieved.
Notes
Do not forget that the ti_Data pointer must point to a ULONG
sized storage location no matter what type you are getting.
See also
AllocLBColumnInfoA(), SetLBColumnInfoAttrsA()
GetListBrowserNodeAttrsA()¶
GetListBrowserNodeAttrsA -- Get attributes about a ListBrowser node.
Synopsis
VOID GetListBrowserNodeAttrs(struct Node *, Tag, ...)
GetListBrowserNodeAttrs(node, firsttag, ...)
VOID GetListBrowserNodeAttrsA(struct Node *, struct TagItem *)
GetListBrowserNodeAttrsA(node, taglist)
Function
The ListBrowser uses a private node structure and all attributes
are hidden, and must therefore be accessed with this function.
TAGS
See SetListBrowserNodeAttrsA() for the list of supported tags.
Inputs
node - The ListBrowser node to get the information on.
Safe to call with a NULL pointer.
taglist - A tag list of attributes to get. ti_Tag is the attribute
to get and ti_Data is a pointer to a location to copy the
result to. The exception is LBNA_Column, which is used to
specify a column to get attributes on.
Safe to call with a NULL pointer.
See also
SetListBrowserNodeAttrsA()
HideAllListBrowserChildren()¶
HideAllListBrowserChildren -- Hide all children in a ListBrowser.
Synopsis
HideAllListBrowserChildren(list);
VOID HideAllListBrowserChildren(struct List *);
Function
Hides all children in a hierarchical ListBrowser, "collapsing" all
generations so that only root generation nodes are shown.
Note that as with any modifications to a ListBrowser list, the list
MUST be detached to the listbrowser at the time of modification.
Inputs
list - a list of ListBrowser nodes, not currently attached to a
ListBrowser. Safe to call with a NULL pointer.
HideListBrowserNodeChildren()¶
HideListBrowserNodeChildren -- Hide a ListBrowser node's children
Synopsis
HideListBrowserNodeChildren(node);
VOID HideListBrowserNodeChildren(struct Node *);
Function
Hides the children of a ListBrowser node. It will only hide the
next generation, nodes of higher generations will not be modified.
Note that as with any modifications to a ListBrowser list, the list
must NOT be attached to the listbrowser at the time of modification.
Inputs
node - the node whose children you will be hiding. The node must
NOT be in a list that that is currently attached to a
ListBrowser. Safe to call with a NULL pointer.
LBM_ADDNODE()¶
LBM_ADDNODE -- Adds a node to the attached list.
Function
Allocates a new node and adds it to the list currently attached to
the listbrowser (if there is one attached). If rendering
information is available, then any necessary refreshing will take
place. You do not need to detach your list first.
This method takes the following message structure:
struct lbAddNode
{
ULONG MethodID; // LBM_ADDNODE
struct GadgetInfo *lba_GInfo; // to provide rendering info
struct Node *lba_Node; // Insert() after this node
struct TagItem *lba_NodeAttrs; // AllocListBrowserNodeA()
// taglist
};
RESULT
Returns a pointer to the allocated node, or NULL on failure.
See also
LBM_EDITNODE, LBM_REMNODE, reaction.lib/LBAddNode
LBM_EDITNODE()¶
LBM_EDITNODE -- Edit an attached nodes attributes.
Function
Changes attributes of a node attached to a listbrowser. If rendering
information is available, then any necessary refreshing will take
place. You do not need to detach your list first.
This method takes the following message structure:
struct lbEditNode
{
ULONG MethodID; // LBM_EDITNODE
struct GadgetInfo *lbe_GInfo; // to provide rendering info
struct Node *lbe_Node; // modify this node
struct TagItem *lbe_NodeAttrs; // SetListBrowserNodeAttrsA()
// taglist
};
RESULT
Returns non-zero on success, zero on failure.
See also
LBM_ADDNODE, LBM_REMNODE, reaction.lib/LBEditNode
LBM_REMNODE()¶
LBM_REMNODE -- Removes a node from the attached list.
Function
Removes and de-allocates a node from the list currently attached
to the listbrowser. If rendering information is available, then
any necessary refreshing will take place. You do not need to
detach your list first.
This method takes the following message structure:
struct lbRemNode
{
ULONG MethodID; // LBM_REMNODE
struct GadgetInfo *lbr_GInfo; // to provide rendering info
struct Node *lbr_Node; // Remove() this node
};
RESULT
Returns non-zero on success, zero on failure.
See also
LBM_ADDNODE, LBM_REMNODE, reaction.lib/LBRemNode
LISTBROWSER_GetClass()¶
LISTBROWSER_GetClass -- Gets the pointer to the listbrowser class.
Synopsis
listbrowser_class = LISTBROWSER_GetClass();
D0
Class * LISTBROWSER_GetClass(VOID);
Function
Obtains the pointer to the ListBrowser gadget class for use with
NewObject(). This function always returns a valid pointer so
you do not need to check it. The reason is that if the library
opens fine, then the pointer returned is already setup. (Of course
this implies that if opening the library fails, you shouldn't be
calling this.)
Note that this function does not create the class, that is done
when the class library is opened.
Inputs
Nothing.
RESULT
listbrowser_class - Pointer to the ListBrowser gadget class.
ListBrowserClearAll()¶
ListBrowserClearAll -- Unselect all nodes in a multiselect ListBrowse r (V45).
Synopsis
ListBrowserClearAll(list);
VOID ListBrowserClearAll(struct List *);
Function
Sets the LBNA_Selected bit to FALSE in all nodes in list. This is a
quick way to unselect all nodes in a multi-select ListBrowser.
Note that as with any modifications to a ListBrowser list, the list
MUST be detached to the listbrowser at the time of modification.
Inputs
list - a list of ListBrowser nodes, not currently attached to a
ListBrowser. Safe to call with a NULL pointer.
See also
ListBrowserSelectAll()
ListBrowserSelectAll()¶
ListBrowserSelectAll -- Select all nodes in a multiselect ListBrowser .
Synopsis
ListBrowserSelectAll(list);
VOID ListBrowserSelectAll(struct List *);
Function
Sets the LBNA_Selected bit to TRUE in all nodes in list. This is a
quick way to select all nodes in a multi-select ListBrowser.
Note that as with any modifications to a ListBrowser list, the list
MUST be detached to the listbrowser at the time of modification.
Inputs
list - a list of ListBrowser nodes, not currently attached to a
ListBrowser.
SetLBColumnInfoAttrsA()¶
SetLBColumnInfoAttrsA -- Sets column info attributes.
Synopsis
VOID SetLBColumnInfoAttrsA(struct ColumnInfo *ci, struct TagItem *tag
s);
VOID SetLBColumnInfoAttrs(struct ColumnInfo *ci, Tag tag1, ...);
Function
Changes attributes for a ColumnInfo structure in a future
friendly manner.
The ColumnInfo array must have been created using the
AllocLBColumnInfoA() function.
You may not change column attributes while the corresponding list
is attached to a ListBrowser gadget. You must first detach the list
with LISTBROWSER_Labels, NULL before you can change attributes and
then re-attach the list along with the LISTBROWSER_ColumnInfo tag.
TAGS
LBCIA_Column (WORD)
A column (starting from 0) that the attribute tags below it
affect. All attribute tags have the prefix LBCIA_#? to
distinguish them from other attributes. You typically specify
the column to work with and then the column attributes. For
example,
...
LBCIA_Column, 0,
LBCIA_Title, "Amiga"
LBCIA_Column, 1,
LBCIA_AutoSort, TRUE,
...
Defaults to 0.
LBCIA_Title (CONST_STRPTR)
The title to assign to the column. This title must be
present if LISTBROWSER_ColumnTitles is TRUE.
Defaults to NULL.
LBCIA_Weight (WORD)
The relative weight to apply to this column expressed
as a percentage value. For example, a value of 40 means
the column should take up 40% of the width. Note that
columns are weighted by default.
Defaults to 0.
LBCIA_Width (WORD)
The specific pixel width of the column. This tag also
implies that the CIF_FIXED flag is set.
Defaults to 0.
LBCIA_Flags (ULONG)
Specifies the flags to be used for this column.
CIF_WEIGHTED -- weighted width column (default)
CIF_FIXED -- fixed pixel width
CIF_DRAGGABLE -- separator is user draggable
CIF_NOSEPARATORS -- no separator on this column
(ignored until V47)
CIF_SORTABLE -- column is sortable (see LBM_SORT)
These flags are deprecated and the equivalent tags
should be used instead.
LBCIA_Sortable (BOOL) (V47)
Column is sortable. This tag is equivalent to the
CIF_SORTABLE flag.
Defaults to FALSE.
LBCIA_SortArrow (BOOL) (V47)
Column has a sort arrow displayed. The arrow will be
displayed either when LBM_SORT is used on this column
or when LBMCIA_AutoSort sort the column automatically.
The direction of the arrow depends on how the column
was sorted. If the LBM_SORT method is use the
lbs_Direction field is used to determine which arrow
to display. If the column is auto-sorted then the
LBMCIA_SortDirection field is used.
Defaults to FALSE.
LBCIA_AutoSort (BOOL) (V47)
Set this flag to allow the gadget to automatically
handle sorting of the column. When the column is
selected the LBM_SORT method will be invoked using the
LBCIA_SortDirection and LBCIA_CompareHook tags.
When the gadget is initially created the column to
sort by is defined using LISTBROWSER_SortColumn.
When the column is selected again the sort direction
will be toggled.
If TRUE then LBCIA_Sortable is also TRUE implicitly.
Defaults to FALSE.
LBCIA_SortDirection (ULONG) (V47)
The current sort direction for the column.
The direction is one of the following values:
LBMSORT_FORWARD -- Forward sort (down sort arrow)
LBMSORT_REVERSE -- Reverse sort (up sort arrow)
The sort direction will automatically toggle when
combined with the LBMCIA_AutoSort tag.
It is possible to use the LBCIA_SortDirection tag and
the LISTBROWSER_SortColumn tag together to save and
restore sorting user preferences.
Defaults to 0 (forward).
LBCIA_CompareHook (struct Hook *) (V47)
The sort comparison hook to use on the column. This is
the exact same hook used by the LBM_SORT method. See
the LBM_SORT method documentation for more information.
This hook will only be used if the column is marked
sortable (see LBCIA_Sortable tag).
Defaults to NULL (default LBM_SORT comparison).
LBCIA_UserData (APTR) (V47)
Arbitrary user data for this column.
Defaults to NULL.
Inputs
ci - Pointer to ColumnInfo array to set attributes on.
Safe to call with a NULL pointer.
tags - A tag list of attributes to set.
Safe to call with a NULL pointer.
RESULT
Returns non-zero on success or 0 on error.
See also
AllocLBColumnInfoA(), GetLBColumnInfoAttrsA()
SetListBrowserNodeAttrsA()¶
SetListBrowserNodeAttrsA -- Set attributes of a ListBrowser node.
Synopsis
VOID SetListBrowserNodeAttrs(struct Node *, Tag, ...)
SetListBrowserNodeAttrs(node, firsttag, ...)
VOID SetListBrowserNodeAttrsA(struct Node *, struct TagItem *)
SetListBrowserNodeAttrsA(node, taglist)
Function
Changes attributes for a ListBrowser node. Since the ListBrowser
class uses a private node structure, this is the only way to change
node attributes.
You may NOT change node attributes when the node is in a list
attached to a ListBrowser gadget. You must first detach the list
with LISTBROWSER_Labels, ~0 before you can change attributes, and
then re-attach the list.
TAGS
LBNA_Selected (BOOL)
If this node is currently selected or not in a multi-select
list browser. This field is not meaningful in a single-
select list browser.
LBNA_Flags (ULONG)
Flags for this node. See ListBrowser.h for available flags.
In particular, you need to set LBFLG_HASCHILDREN for non-leaf
nodes in hierarchical listbrowsers.
LBNA_Generation (WORD)
Sets which "generation" this node belongs to, if the ListBrowser
is to be in hierarchical mode. If you were to draw the nodes out
in a sort of family tree, the generation would refer to the level
in the tree.
Generations start at 1. A generation 1 node's children will be
generation 2, you cannot skip generations. Nodes need not have
children and generations can go as deep as you like, limited by
the available stack of input.device.
LBNA_UserData (APTR)
Arbitrary user data for this node.
LBNA_Column (WORD)
A column (from 0 to number_of_columns-1) that the column
attribute tags below (LBNCA_Text, LBNA_Integer, LBNA_FGPen,
LBNA_BGPen, LBNA_Image, LBNA_SelImage, LBNA_Justification)
affect. You typically specify the column to work on, and
then the column attributes for that column, then the next
column followed by its attributes, etc.
LBNCA_Text (STRPTR)
Text that is to appear in the corresponding column for
this node. Only one of LBNCA_Text, LBNA_Integer and
LBNCA_Image may be non-NULL, specifying the type of contents
for this column. Each column of a node need not have the
same type of contents. Similarly, the same column in
different nodes also need not have the same type of contents.
LBNCA_CopyText (BOOL)
Specifies that you want the LBNCA_Text copied to an internal
buffer by ListBrowser. Note: this tag must precede LBNCA_Text
in the tag list!
LBNCA_Editable (BOOL)
Specifies that this item can be edited. If the user clicks
twice on this entry, the text will become a string gadget
where the user can edit the contents. This will only work
if the contents are text (given with LBNCA_Text) AND if
LBNCA_CopyText was used. You MUST also specify LBNCA_MaxChars
to specify how long the edited text can be.
LBNCA_MaxChars(WORD)
Maximum number of characters an editable text entry can be.
LBNCA_Integer (LONG *)
A pointer to an integer to display in this column, or NULL.
LBNCA_FGPen, LBNA_BGPen (WORD)
The pens to be used for rendering the text or integer in
this column. Requires that the LBFLG_CUSTOMPENS flag be
specified, otherwise the default system pens will be used.
LBNCA_FillPen (WORD) (V47)
The pen to be used for rendering the background for the text
or integer in this column when it is selected. Requires that
the LBFLG_CUSTOMPENS flag in LBNA_Flags be specified,
otherwise the default system pen will be used.
Defaults to FILLPEN. Applicability is OM_NEW, OM_SET, OM_GET.
LBNCA_Image, LBNA_SelImage (struct Image *)
Specifies that the column should contain an image. The
selected image is optional, if not provided, LBNA_Image will
be rendered in the IDS_SELECTED state when then node is
selected.
LBNCA_Justification (WORD)
Specifies a justification for the column, either LCJ_LEFT,
LCJ_CENTRE or LCJ_RIGHT.
Defaults to LCJ_LEFT
LBNCA_VertJustify (WORD) (V47)
Specifies a vertical justification for the column either
LRJ_TOP, LRJ_CENTER or LRJ_BOTTOM.
Defaults to LRJ_CENTER.
LBNA_CheckBox (BOOL) (V41)
Means that this node will be a checkbox node, that can be toggled
on or off.
Defaults to FALSE.
LBNA_Checked (BOOL) (V41)
Indicates whether a checkbox node is in the checked or unchecked
state.
Defaults to FALSE.
LBNCA_EditTags (struct TagItem *) (V41)
Tags that you want to be passed to the string gadget used when
editing gadget text. Though you could theoretically pass any
tags to the gadget, you should generally not pass tags that
affect the position of the gadget.
Defaults to NULL.
LBNCA_RenderHook (struct Hook *) (V41)
A custom render hook for this node column. Your hook will
receive a pointer to struct Node of the node in question as its
object, and the following structure in the message pointer:
struct LBDrawMsg
{
ULONG lbdm_MethodID; // LV_DRAW
struct RastPort *lbdm_RastPort; // Where to render to
struct DrawInfo *lbdm_DrawInfo; // Useful to have around
struct Rectangle lbdm_Bounds; // Limits of where to render
ULONG lbdm_State; // How to render
};
LBDrawMsg.lbdm_State will be either LBR_SELECTED or LBR_NORMAL. The
hook should return LBCB_OK if rendering was successful, or
LBCB_UNKNOWN if lbdm_Method doesn't equal LV_DRAW. No rendering
should be performed in this case.
Note that this is HIGHLY compatible with a GadTools listview hook.
Defaults to NULL.
LBNCA_HookHeight (WORD) (V41)
The height of this column, when using LBNCA_RenderHook.
LBNA_MemPool (APTR) (V42)
Specifies a custom memory pool to allocate listbrowser nodes from.
Please note that when creating the memory pool, you need to specify
the MEMF_CLEAR flag otherwise listbrowser.gadget will crash. This
is fixed for V45.1.
Defaults to NULL (internal pool).
LBNCA_WordWrap (BOOL) (V42)
Specifies this column's text can be word wrapped. Useful in
weighted column displays or fixed pixels columns. Primarily
this feature exists at the request of IRC client authors.
Initial implementation in V42.630 is slow. Improvement to be made.
Defaults to FALSE.
Inputs
node - Node whose attributes you are changing.
Safe to call with a NULL pointer.
taglist - Tag list of attributes to change.
Safe to call with a NULL pointer.
See also
GetListBrowserNodeAttrsA()
ShowAllListBrowserChildren()¶
ShowAllListBrowserChildren -- Show all children in a ListBrowser
Synopsis
ShowAllListBrowserChildren(list);
VOID ShowAllListBrowserChildren(struct List *);
Function
Shows all children in a hierarchical ListBrowser, no matter what
generation they are in.
Note that as with any modifications to a ListBrowser list, the list
must NOT be attached to the listbrowser at the time of modification.
Inputs
list - a list of ListBrowser nodes, not currently attached to a
ListBrowser. Safe to call with a NULL pointer.
ShowListBrowserNodeChildren()¶
ShowListBrowserNodeChildren -- Show children of a ListBrowser node.
Synopsis
ShowListBrowserNodeChildren(node, depth);
VOID ShowListBrowserNodeChildren(struct Node *, WORD);
Function
Show the children of a ListBrowser node. The next depth generations
will be shown. To only show the next generation, use a depth of 1.
Note that as with any modifications to a ListBrowser list, the list
must NOT be attached to the listbrowser at the time of modification.
Inputs
node - the node whose children you will be showing. The node must
NOT be in a list that that is currently attached to a
ListBrowser. Safe to call with a NULL pointer.
depth - how many generations deep to show.