MUI Autodocs: List.mui

Copyright © 1998, Stefan Stuntz




List.mui Background

        MUI's list class is very powerful. It handles all types
        of entries, from a simple string to a complicated structure
        with many associated resources. Multi column lists are
        also supported, the format for a column is adjustable.

        Lists support any kind of sorting, multi selection and
        an active entry that can be controlled with the mouse
        or the cursor keys.

        Note: A list object alone doesn't make much sense, you
              should always use it as child of a listview object.
              This one attaches a scrollbar and handles all user
              input.



List.mui Attributes

    Attribute                           Ver ISG Type
    ----------------------------------- --- --- --------------------
    MUIA_List_Active                    V4  ISG LONG
    MUIA_List_AdjustHeight              V4  I.. BOOL
    MUIA_List_AdjustWidth               V4  I.. BOOL
    MUIA_List_AutoVisible               V11 ISG BOOL
    MUIA_List_CompareHook               V4  IS. struct Hook *
    MUIA_List_ConstructHook             V4  IS. struct Hook *
    MUIA_List_DestructHook              V4  IS. struct Hook *
    MUIA_List_DisplayHook               V4  IS. struct Hook *
    MUIA_List_DragSortable              V11 ISG BOOL
    MUIA_List_DropMark                  V11 ..G LONG
    MUIA_List_Entries                   V4  ..G LONG
    MUIA_List_First                     V4  ..G LONG
    MUIA_List_Format                    V4  ISG STRPTR
    MUIA_List_InsertPosition            V9  ..G LONG
    MUIA_List_MinLineHeight             V4  I.. LONG
    MUIA_List_MultiTestHook             V4  IS. struct Hook *
    MUIA_List_Pool                      V13 I.. APTR
    MUIA_List_PoolPuddleSize            V13 I.. ULONG
    MUIA_List_PoolThreshSize            V13 I.. ULONG
    MUIA_List_Quiet                     V4  .S. BOOL
    MUIA_List_ShowDropMarks             V11 ISG BOOL
    MUIA_List_SourceArray               V4  I.. APTR
    MUIA_List_Title                     V6  ISG char *
    MUIA_List_Visible                   V4  ..G LONG



List.mui Methods

    Method                              Ver
    ----------------------------------- ---
    MUIM_List_Clear                     V4  
    MUIM_List_CreateImage               V11 
    MUIM_List_DeleteImage               V11 
    MUIM_List_Exchange                  V4  
    MUIM_List_GetEntry                  V4  
    MUIM_List_Insert                    V4  
    MUIM_List_InsertSingle              V7  
    MUIM_List_Jump                      V4  
    MUIM_List_Move                      V9  
    MUIM_List_NextSelected              V6  
    MUIM_List_Redraw                    V4  
    MUIM_List_Remove                    V4  
    MUIM_List_Select                    V4  
    MUIM_List_Sort                      V4  
    MUIM_List_TestPos                   V11 


MUIA_List_Active


    NAME
        MUIA_List_Active -- (V4 ) [ISG], LONG

    SPECIAL INPUTS
        MUIV_List_Active_Off
        MUIV_List_Active_Top
        MUIV_List_Active_Bottom
        MUIV_List_Active_Up
        MUIV_List_Active_Down
        MUIV_List_Active_PageUp
        MUIV_List_Active_PageDown

    FUNCTION
        Reading this attribute will return the number of
        the active entry (the one with the cursor on it).
        The result is between 0 and MUIA_List_Entries-1
        or MUIV_List_Active_Off, in which case there is
        currently no active entry.

        Setting the attribute will cause the list to
        move the cursor to the new position and scroll
        this position into the visible area.

    SEE ALSO
        MUIA_List_Entries, MUIA_List_First, MUIA_List_Visible


MUIA_List_AdjustHeight


    NAME
        MUIA_List_AdjustHeight -- (V4 ) [I..], BOOL

    FUNCTION
        A list with MUIA_List_AdjustHeight set to true is exactly
        as high as all of its entries and not resizable. This is
        only possible when the list is filled *before* the window
        is opened.

    SEE ALSO
        MUIA_List_AdjustWidth


MUIA_List_AdjustWidth


    NAME
        MUIA_List_AdjustWidth -- (V4 ) [I..], BOOL

    FUNCTION
        A list with MUIA_List_AdjustWidth set to true is exactly
        as wide as the widest entry and not resizable. This is
        only possible when the list is filled *before* the window
        is opened.

    SEE ALSO
        MUIA_List_AdjustHeight


MUIA_List_AutoVisible


    NAME
        MUIA_List_AutoVisible -- (V11) [ISG], BOOL

    FUNCTION
        Set this to make your lists automatically jump to the
        active entry when they are displayed.

    SEE ALSO
        MUIA_List_Active


MUIA_List_CompareHook


    NAME
        MUIA_List_CompareHook -- (V4 ) [IS.], struct Hook *

    FUNCTION
        If you plan to have the entries of your list sorted
        (either by inserting them sorted or by using the
        MUIM_List_Sort method) and if the entries of your
        list are not simple strings, you *must* supply
        a compare hook.

        This hook will be called with one list element in A1
        and another one in A2. You should return something like

        <0   e1 <  e2
         0   e1 == e2
        >0   e1 >  e2

    EXAMPLE
        /* the builtin string compare function */

        LONG __asm cmpfunc(_a1 char *s1,_a2 char *s2)
        {
           return(stricmp(s1,s2));
        }

    SEE ALSO
        MUIA_List_ConstructHook, MUIA_List_DestructHook


MUIA_List_ConstructHook


    NAME
        MUIA_List_ConstructHook -- (V4 ) [IS.], struct Hook *

    SPECIAL INPUTS
        MUIV_List_ConstructHook_String

    FUNCTION
        The construct hook is called whenever you add an
        entry to your list. MUI will not insert the given
        pointer directly, but instead call the construct
        hook and add its result code.

        Imagine you want to display a list of entries
        in a directory. You could step through it
        using Examine()/ExNext() and directly use the
        MUIM_List_Insert method on your file info block
        buffer.

        Your construct hook will be called with this
        file info block as parameter, makes a copy of
        it and returns the address of that copy. Thats
        what is actually added to the list.

        The corresponding destruct hook is called whenever
        an entry shall be removed. It's task would simply be
        to free the memory and maybe other resources concering
        this entry that were allocated by the construct hook.

        Using these two functions, you will never have to
        worry about freeing the memory used by your list
        entries. Clearing the list or disposing the list
        object will automatically remove all entries and
        thus free the associated resources.

        The construct hook will be called with the hook
        in A0, the data given to MUIM_List_Insert as message
        in register A1 and with pointer to a standard kick 3.x
        memory pool in A2. If you want, you can use the exec
        or amiga.lib functions for allocating memory within
        this pool, but this is only an option.

        If the construct hook returns NULL, nothing will be
        added to the list.

        There is a builtin construct hook available called
        MUIV_List_ConstructHook_String. This expects that
        you only add strings to your list and will make
        a local copy of this string to allow you destroying
        the original. Of course you *must* also use
        MUIV_List_DestructHook_String in this case.

        Without construct and destruct hooks, you are responsible
        for allocating and freeing entries yourself.

    EXAMPLE
        /* the builtin string construct and destruct functions: */

        APTR __asm consfunc(_a2 APTR pool,_a1 char *str)
        {
           char *new;
           if (new=AllocPooled(pool,strlen(str)+1))
              strcpy(new,str);
           return(new);
        }

        VOID __asm desfunc(_a2 APTR pool,_a1 char *entry)
        {
           FreePooled(pool,entry,strlen(entry)+1);
        }

        /* for more sophisticated hooks see demo program WbMan.c */

    SEE ALSO
        MUIA_List_DestructHook, MUIA_List_DisplayHook


MUIA_List_DestructHook


    NAME
        MUIA_List_DestructHook -- (V4 ) [IS.], struct Hook *

    SPECIAL INPUTS
        MUIV_List_DestructHook_String

    FUNCTION
        Set up a destruct hook for your list. For detailed
        explanation see MUIA_List_ConstructHook.

    SEE ALSO
        MUIA_List_ConstructHook, MUIA_List_DisplayHook


MUIA_List_DisplayHook


    NAME
        MUIA_List_DisplayHook -- (V4 ) [IS.], struct Hook *

    FUNCTION
        Since MUI's lists can handle any kind of entries,
        you have to supply a display hook to specify what
        should actually be shown in the display.

        The hook will be called with a pointer to the
        entry to be displayed in A1 and a pointer to
        a string array containing as many entries as
        your list may have columns in A2.

        You must fill this array with the strings that
        you want to display.

        Note: You can of course use MUI's text engine
              facilities here to create e.g. right aligned
              or centered columns.

        Without a display hook, MUI expects a simple one
        columned string list.

        See MUIA_List_Format for details about column handling.

        Note: Since version 6 of MUI, the display hook also gets the
        position of the current entry as additional parameter. You
        can easily do e.g. some line numbering using this feature. The
        number (from 0 to NumEntries-1) is stored in the longword
        *preceding* the column array (see example below).

    EXAMPLE
        /* list of file info blocks, two columned, name and size */

        LONG __asm dispfunc(_a2 char **array,_a1 struct FileInfoBlock *fib)
        {
           static char buf1[20],buf2[20];

           if (fib->fib_EntryType<0)
             sprintf(buf2,"\33r%ld",fib->fib_Size);
           else
             strcpy(buf2,"\33r(dir)");

           sprintf(buf1,"%ld",array[-1]);   // get the line number.

           *array++ = buf1;
           *array++ = fib->fib_FileName;
           *array   = buf2;

           return(0);
        }

    SEE ALSO
        MUIA_List_Format, MUIA_Text_Contents


MUIA_List_DragSortable


    NAME
        MUIA_List_DragSortable -- (V11) [ISG], BOOL

    FUNCTION
        If you set this attribute to TRUE, the user will be able
        to move around entries in the list by using drag&drop.


MUIA_List_DropMark


    NAME
        MUIA_List_DropMark -- (V11) [..G], LONG

    FUNCTION
        After a successfull drop operation, this attribute holds
        the position where we should insert the new entry(ies).
        
    EXAMPLE
        See DragnDrop example program


MUIA_List_Entries


    NAME
        MUIA_List_Entries -- (V4 ) [..G], LONG

    FUNCTION
        Get the current number of entries in the list.

    SEE ALSO
        MUIA_List_First, MUIA_List_Visible, MUIA_List_Active


MUIA_List_First


    NAME
        MUIA_List_First -- (V4 ) [..G], LONG

    FUNCTION
        Get the number of the entry displayed on top of
        the list. You have to be prepared to get a result
        of -1, which means that the list is not visible
        at all (e.g. when the window is iconifed).

    SEE ALSO
        MUIA_List_Visible, MUIA_List_Entries, MUIA_List_Active


MUIA_List_Format


    NAME
        MUIA_List_Format -- (V4 ) [ISG], STRPTR

8    FUNCTION
        MUI has the ability to handle multi column lists. To define
        how many columns should be displayed and how they should be
        formatted, you specify a format string.

        This format string must contain one entry for each column
        you want to see. Entries are seperated by commas, one
        entry is parsed via dos.library/ReadArgs().

        The template for a single entry looks like this:

        DELTA=D/N,PREPARSE=P/K,WEIGHT=W/N,
        MINWIDTH=MIW/N,MAXWIDTH=MAW/N,COL=C/N,BAR/S

        DELTA
           Space in pixel between this column and the next.
           the last displayed column ignores this setting.
           Defaults to 4.

        PREPARSE
           A preparse value for this column. Setting this
           e.g. to "\33c" would make the column centered.
           See MUIA_Text_Contents for other control codes.

        WEIGHT
           The weight of the column. As with MUI's group
           class, columns are layouted with a minimum
           size, a maximum size and weight. A column with
           a weight of 200 would gain twice the space than
           a column with a weight of 100.
           Defaults to 100.

        MINWIDTH
           Minimum percentage width for the current column.
           If your list is 200 pixel wide and you set this
           to 25, your column will at least be 50 pixel.
           The special value -1 for this parameter means that
           the minimum width is as wide as the widest entry in
           this column. This ensures that every entry will be
           completely visible (as long as the list is wide enough).
           Defaults to -1.

        MAXWIDTH
           Maximum percentage width for the current column.
           If your list is 200 pixel wide and you set this
           to 25, your column will not be wider as 50 pixel.
           The special value -1 for this parameter means that
           the maximum width is as wide as the widest entry in
           this column.
           Defaults to -1.

        COL
           This value adjusts the number of the current column.
           This allows you to adjust the order of your columns
           without having to change your display hook. See
           example for details.
           Defaults to current entry number (0,1,...)

        BAR
           Since muimaster.library V11, you can enable a
           vertical bar between this and the next column by
           using this switch.

        If your list object gets so small there is not enough
        place for the minwidth of a column, this column will
        be hidden completely and the remaining space is
        distributed between the remaining columns. This is not
        true if the column is the first column, in this case
        the entries will simply be clipped.

        Note: You will have as many columns in your list as
              entries in the format string (i.e. number of
              commas + 1). Empty entries, e.g. with a format
              string of ",,,," are perfectly ok.

        The default list format is an empty string (""), this
        means a one column list without special formatting.

    BUGS
        Currently there is a maximum of 64 columns for a list.

    EXAMPLE
        /* Three column list without further formatting: */
        MUIA_List_Format: ",,"

        /* Three column list, middle column centered: */
        MUIA_List_Format: ",P=\33c,"

        /* Three column list, display order 2 1 0: */
        MUIA_List_Format: "COL=2,COL=1,COL=0"

        /* now something more complex.           */
        /* the display hook defines six entries: */
        dispfunc(_a2 char **array,_a1 struct Article *at)
        {
           *array++ = at->FromName; // col 0
           *array++ = at->FromPath; // col 1
           *array++ = at->ToName;   // col 2
           *array++ = at->ToPath;   // col 3
           *array++ = at->Date;     // col 4
           *array   = at->Subject;  // col 5
        }

        /* but we only want to have fromname, date and subject
        /* actually displayed, subject shoud be centered: */
        MUIA_List_Format, "COL=0,COL=4,COL=5 P=\33c"

        /* maybe this looks kind of silly, why not make our  */
        /* display hook only fill in these three columns.    */
        /* well, if you would e.g. make the format string    */
        /* user configurable and document what your display  */
        /* hook puts into the array, the user could decide   */
        /* what columns he actually wants to see.            */
        /* The supplied example DFView does something like   */
        /* that.                                             */

        /* two column list:   ! Eye    1234 !
                              ! Foot     22 !
                              ! Nose  22331 ! */

        MUIA_List_Format, "MAW=100,P=\33r"

    SEE ALSO
        MUIA_List_DisplayHook, MUIA_Text_Contents


MUIA_List_InsertPosition


    NAME
        MUIA_List_InsertPosition -- (V9 ) [..G], LONG

    FUNCTION
        After insertion of an element with MUIM_List_Insert,
        you can query the position of the new entry by
        getting this attribute.


MUIA_List_MinLineHeight


    NAME
        MUIA_List_MinLineHeight -- (V4 ) [I..], LONG

    FUNCTION
        Sets the minimum line height for lists in pixels. Useful
        e.g. if you have custom images.


MUIA_List_MultiTestHook


    NAME
        MUIA_List_MultiTestHook -- (V4 ) [IS.], struct Hook *

    FUNCTION
        If you plan to have a multi selecting list but not
        all of your entries are actually multi selectable
        (e.g. in a file requester), you can supply a
        MUIA_List_MultiTestHook.

        It will be called with a pointer to an entry in
        A1 and should return TRUE if the entry is multi
        selectable, FALSE otherwise.

    EXAMPLE
        /* multi test func for a list of file info blocks */

        LONG __asm mtfunc(_a1 struct FileInfoBlock *fib)
        {
           if (fib->fib_DirEntryType<0)
              return(TRUE);
           else
              return(FALSE);
        }

    SEE ALSO
        MUIA_List_ConstructHook, MUIA_List_DestructHook


MUIA_List_Pool


    NAME
        MUIA_List_Pool -- (V13) [I..], APTR

    FUNCTION
        Pass something from CreatePool() here if you dont want the list 
        to create its own memory pool but use this one instead. Note 
        that list class does *not* use semaphore protection when 
        accessing the pool, you must *not* use pools which are 
        accessed from different tasks than the applications main
        task.

    SEE ALSO
        MUIA_List_PoolPuddleSize, MUIA_List_PoolThreshSize


MUIA_List_PoolPuddleSize


    NAME
        MUIA_List_PoolPuddleSize -- (V13) [I..], ULONG

    FUNCTION
        Specify the puddle size for the lists memory pool.
        Defaults to 2008. Is ignored if you specify your
        own pool with MUIA_List_Pool.

    SEE ALSO
        MUIA_List_PoolThreshSize, MUIA_List_Pool


MUIA_List_PoolThreshSize


    NAME
        MUIA_List_PoolThreshSize -- (V13) [I..], ULONG

    FUNCTION
        Specify the thresh size for the lists memory pool.
        Defaults to 1024. Is ignored if you specify your
        own pool with MUIA_List_Pool.

    SEE ALSO
        MUIA_List_PoolPuddleSize, MUIA_List_Pool


MUIA_List_Quiet


    NAME
        MUIA_List_Quiet -- (V4 ) [.S.], BOOL

    FUNCTION
        If you add/remove lots of entries to/from a currently visible
        list, this will cause lots of screen action and slow down
        the operation. Setting MUIA_List_Quiet to true will
        temporarily prevent the list from being refreshed, this
        refresh will take place only once when you set it back
        to false again.

    EXAMPLE
        set(list,MUIA_List_Quiet,TRUE);
        AddThousandEntries(list);
        set(list,MUIA_List_Quiet,FALSE);

    SEE ALSO
        MUIM_List_Insert, MUIM_List_Remove


MUIA_List_ShowDropMarks


    NAME
        MUIA_List_ShowDropMarks -- (V11) [ISG], BOOL

    FUNCTION
        If a list supports Drag & Drop, it usually indicates the place
        where a new line would be inserted with some horizontal lines.

        Showing this place doesnt make much sense if you dont care
        about the drop position anyway, e.g. because your list is
        always alphabetically sorted. You should set this attribute
        to FALSE in these cases.

    SEE ALSO
        MUIA_List_DropMark


MUIA_List_SourceArray


    NAME
        MUIA_List_SourceArray -- (V4 ) [I..], APTR

    FUNCTION
        The NULL terminated array given here is immediately inserted into the
        list after object creation time.

    EXAMPLE
        static const char *KeyList[] =
        {
           "Cursor Up",
           "Cursor Down",
           "Cursor Left",
           "Cursor Right",
           NULL;
        };

        LV_Keys = ListviewObject,
           MUIA_Listview_List, ListObject,
              InputListFrame,
              MUIA_List_AdjustWidth, TRUE,
              MUIA_List_SourceArray, KeyList,
              End,
           End;


MUIA_List_Title


    NAME
        MUIA_List_Title -- (V6 ) [ISG], char *

    FUNCTION
        Specify a title for the current list. The title is displayed
        at the very first line and doesn't scroll away when the list
        top position moves.

        Usually, the title is just a string. However, if you have
        a multi column list with a custom display hook and you
        want to have seperate titles for each of your columns,
        you can set this attribute to TRUE. In this case, whenever
        MUI feels that the list title has to be drawn, it will
        call your display hook with a NULL entry pointer. Your
        hook has to check for this NULL entry and fill the
        given string array with your column titles. Layout of
        the column titles follows the same rules as layout
        of the lists entries.

    EXAMPLE

        /* display function for a multi columned file list with titles */

        LONG __asm DisplayFunc(_a2 char **array,_a1 struct Entry *e)
        {
           struct Data *data = hook->h_Data;

           if (e)
           {
              *array++ = e->Name;
              *array++ = e->Size;
              *array++ = e->Date;
              *array++ = e->Time;
              *array++ = e->Flags;
              *array   = e->Comment;
           }
           else
           {
              *array++ = "Name";
              *array++ = "Size";
              *array++ = "Date";
              *array++ = "Time";
              *array++ = "Flags";
              *array   = "Comment";
           }

           return(0);
        }

    SEE ALSO
        MUIA_List_DisplayHook


MUIA_List_Visible


    NAME
        MUIA_List_Visible -- (V4 ) [..G], LONG

    FUNCTION
        Get the current number of visible entries in the list.
        You have to be prepared to get a result
        of -1, which means that the list is not visible
        at all (e.g. when the window is iconifed).

    SEE ALSO
        MUIA_List_First, MUIA_List_Entries, MUIA_List_Active


MUIM_List_Clear


    NAME
        MUIM_List_Clear (V4 )

    SYNOPSIS
        DoMethod(obj,MUIM_List_Clear);

    FUNCTION
        Clear the list, all entries are removed. If a destruct
        hook is set it will be called for every entry.

    SEE ALSO
        MUIM_List_Insert, MUIA_List_DestructHook


MUIM_List_CreateImage


    NAME
        MUIM_List_CreateImage (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_List_CreateImage,Object *obj, ULONG flags);

    FUNCTION
        If you want to have custom images in a listview (e.g.
        like the little monitor icons in PSI), you should create
        them as Bitmap objects (or Bodychunk objects) in the
        setup method of your list class (use a subclass!). 

        After that, pass the newly created object pointer to
        MUIM_List_CreateImage and use the result in your display
        hook with

        \33O[%08lx]

        where %08lx must be replaced by the pointer you got
        from MUIM_List_CreateImage.

        When your list is done (i.e. in the Cleanup method),
        kill your image with MUIM_List_DeleteImage and
        dispose your object.

    RESULT
        The result you get is a black box pointer, it's not valid
        to assume anything about it. The only useful thing you can
        do is to include it in \33O[%08lx]. The result may be NULL
        in which case MUI was unable to create the image, but the
        \33O[] combination simply draws nothing when receiving a
        NULL so it shouldnt be considered an error.

    EXAMPLE
        See ScreenList class in screen inspector source code psi.c

    SEE ALSO
        MUIM_List_DeleteImage


MUIM_List_DeleteImage


    NAME
        MUIM_List_DeleteImage (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_List_DeleteImage,APTR listimg);

    FUNCTION
        Delete the image pointer returned from MUIM_List_CreateImage.

    SEE ALSO
        MUIM_List_DeleteImage


MUIM_List_Exchange


    NAME
        MUIM_List_Exchange (V4 )

    SYNOPSIS
        DoMethod(obj,MUIM_List_Exchange,LONG pos1, LONG pos2);

    FUNCTION
        Exchange two entries in a list.

    INPUTS
        pos1 - number of the first entry.
        pos2 - number of the second entry.

        Possible special values since muimaster.library V9:

        MUIV_List_Exchange_Top       0
        MUIV_List_Exchange_Active   -1
        MUIV_List_Exchange_Bottom   -2
        MUIV_List_Exchange_Next     -3 /* only valid for second parameter */
        MUIV_List_Exchange_Previous -4 /* only valid for second parameter */

    SEE ALSO
        MUIM_List_Insert, MUIM_List_Remove, MUIM_List_Move


MUIM_List_GetEntry


    NAME
        MUIM_List_GetEntry (V4 )

    SYNOPSIS
        DoMethod(obj,MUIM_List_GetEntry,LONG pos, APTR *entry);

    FUNCTION
        Get an entry of a list.

    INPUTS
        pos   - Number of entry, MUIV_List_GetEntry_Active can
                be used to get the active entry.

        entry - Pointer to a longword where the entry will
                be stored. If the entry is not available
                (either because you are out of bounds or
                because there is no active entry), you will
                receive a NULL.

    EXAMPLE
        /* iterate through a list containing file info blocks */

        for (i=0;;i++)
        {
            struct FileInfoBlock *fib;

            DoMethod(list,MUIM_List_GetEntry,i,&fib);
            if (!fib) break;

            printf("%s\n",fib->fib_FileName);
        }

    SEE ALSO
        MUIM_List_Insert, MUIM_List_Remove


MUIM_List_Insert


    NAME
        MUIM_List_Insert (V4 )

    SYNOPSIS
        DoMethod(obj,MUIM_List_Insert,APTR *entries, LONG count, LONG pos);

    FUNCTION
        Insert new entries into a list.
        When the list has a construct hook, the given pointers
        won't be inserted directly but instead passed through 
        to the construct hook.

    INPUTS
        entries - pointer to an array of pointers to be inserted.
                  Warning: This is a pointer to a pointer. See
                  example for details.

        count   - Number of elements to be inserted. If count==-1,
                  entries will be inserted until NULL pointer in
                  the entries array is found.

        pos     - New entries will be added in front of this entry.
                  MUIV_List_Insert_Top:
                     insert as first entry.
                  MUIV_List_Insert_Active:
                     insert in front of the active entry.
                  MUIV_List_Insert_Sorted:
                     insert sorted.
                  MUIV_List_Insert_Bottom:
                     insert as last entry.

                  If pos is bigger or equal to the number of entries
                  in the list, it's treated like MUIV_List_Insert_Bottom.

    EXAMPLE
        /* insert a string */
        char *str = "New entry";
        DoMethod(list,MUIM_List_Insert,&str,1,MUIV_List_Insert_Bottom);

        /* insert an array */
        char *str[] =
        {
           "Entry 1",
           "Entry 2",
           "Entry 3",
           "Entry 4",
           NULL
        };
        DoMethod(list,MUIM_List_Insert,str,-1,MUIV_List_Insert_Bottom);

    SEE ALSO
        MUIM_List_Remove, MUIA_List_ConstructHook


MUIM_List_InsertSingle


    NAME
        MUIM_List_InsertSingle (V7 )

    SYNOPSIS
        DoMethod(obj,MUIM_List_InsertSingle,APTR entry, LONG pos);

    FUNCTION
        Insert one new entry into a list. Using MUIM_List_Insert has
        caused some confusion since it takes an array to items instead
        a single item. To insert single items, MUIM_List_InsertSingle
        is the better choice.

        When the list has a construct hook, the given pointer
        won't be inserted directly but instead passed through
        to the construct hook.

    INPUTS
        entry   - item to insert.

        pos     - New entry will be added in front of this entry.
                  MUIV_List_Insert_Top:
                     insert as first entry.
                  MUIV_List_Insert_Active:
                     insert in front of the active entry.
                  MUIV_List_Insert_Sorted:
                     insert sorted.
                  MUIV_List_Insert_Bottom:
                     insert as last entry.

                  If pos is bigger or equal to the number of entries
                  in the list, it's treated like MUIV_List_Insert_Bottom.

    EXAMPLE
        /* insert a string */
        DoMethod(list,MUIM_List_InsertSingle,"foobar",MUIV_List_Insert_Bottom);

    SEE ALSO
        MUIM_List_Remove, MUIA_List_ConstructHook, MUIM_List_InsertSingle


MUIM_List_Jump


    NAME
        MUIM_List_Jump (V4 )

    SYNOPSIS
        DoMethod(obj,MUIM_List_Jump,LONG pos);

    FUNCTION
        Scroll any entry into the visible part of a list.

        Note: Jumping to an entry doesn't mean to make this
              entry the active one. This can be done by 
              setting the MUIA_List_Active attribute.

    INPUTS
        pos - Number of the entry that should be made visible.
              Use MUIV_List_Jump_Active to jump to the active
              entry.

    EXAMPLE
        /* line 42 is interesting, so make it visible */
        DoMethod(list,MUIM_List_Jump,42);

    SEE ALSO
        MUIA_List_Active


MUIM_List_Move


    NAME
        MUIM_List_Move (V9 )

    SYNOPSIS
        DoMethod(obj,MUIM_List_Move,LONG from, LONG to);

    FUNCTION
        Move an entry from one position to another.

    INPUTS
        pos1 - number of the first entry.
        pos2 - number of the second entry.

        Possible special values since muimaster.library V9:

        MUIV_List_Move_Top       0
        MUIV_List_Move_Active   -1
        MUIV_List_Move_Bottom   -2
        MUIV_List_Move_Next     -3 /* only valid for second parameter */
        MUIV_List_Move_Previous -4 /* only valid for second parameter */

    SEE ALSO
        MUIM_List_Insert, MUIM_List_Remove, MUIM_List_Exchange


MUIM_List_NextSelected


    NAME
        MUIM_List_NextSelected (V6 )

    SYNOPSIS
        DoMethod(obj,MUIM_List_NextSelected,LONG *pos);

    FUNCTION
        Iterate through the selected entries of a list.
        This method steps through the contents of a (multi
        select) list and returns every entry that is currently
        selected. When no entry is selected but an entry is
        active, only the active entry will be returned.

        This behaviour will result in not returning the
        active entry when you have some other selected
        entries somewhere in your list. Since the active
        entry just acts as some kind of cursor mark,
        this seems to be the only sensible possibility
        to handle multi selection together with keyboard
        control.

    INPUTS
        pos - a pointer to longword that will hold the number
              of the returned entry. Must be set to 
              MUIV_List_NextSelected_Start at start of iteration. 
              Is set to MUIV_List_NextSelected_End when iteration
              is finished.

    EXAMPLE

        /* Iterate through a list with FileInfoBlocks */

        struct FileInfoBlock *fib;
        LONG id = MUIV_List_NextSelected_Start;

        for (;;)
        {
           DoMethod(list,MUIM_List_NextSelected,&id);
           if (id==MUIV_List_NextSelected_End) break;

           DoMethod(list,MUIM_List_GetEntry,id,&fib);
           printf("selected: %s\n",fib->fib_FileName);
        }


    SEE ALSO
        MUIM_List_Select


MUIM_List_Redraw


    NAME
        MUIM_List_Redraw (V4 )

    SYNOPSIS
        DoMethod(obj,MUIM_List_Redraw,LONG pos);

    FUNCTION
        If you made some changes to an entry of your list and
        want these changes to be shown in the display, you will
        have to call this method.

    INPUTS
        pos - Number of the line to redraw. When the line is not
              currently visible, nothing will happen. Specials:
              MUIV_List_Redraw_Active:
                 redraw the active line (if any),
              MUIV_List_Redraw_All:
                 redraw all lines.

    EXAMPLE
        /* do a complete refresh: */
        DoMethod(list,MUIM_List_Redraw,MUIV_List_Redraw_All);


MUIM_List_Remove


    NAME
        MUIM_List_Remove (V4 )

    SYNOPSIS
        DoMethod(obj,MUIM_List_Remove,LONG pos);

    FUNCTION
        Remove an entry from a list.

    INPUTS
        pos - number of the entry to be removed or one of
              MUIV_List_Remove_First,
              MUIV_List_Remove_Active,
              MUIV_List_Remove_Last.
              MUIV_List_Remove_Selected.
              When the active entry is removed, the following entry
              will become active.

    EXAMPLE
        /* when delete is pressed, remove the active entry */
        DoMethod(btdel,MUIM_Notify,MUIA_Pressed,FALSE,
           list,2,MUIM_List_Remove,MUIV_List_Remove_Active);

    SEE ALSO
        MUIM_List_Insert, MUIA_List_DestructHook


MUIM_List_Select


    NAME
        MUIM_List_Select (V4 )

    SYNOPSIS
        DoMethod(obj,MUIM_List_Select,LONG pos, LONG seltype, LONG *state);

    FUNCTION
        Select/deselect a list entry or ask an entry if its
        selected.

    INPUTS

        pos     - Number of the entry or
                  MUIV_List_Select_Active for the active entry.
                  MUIV_List_Select_All    for all entries.

        seltype - MUIV_List_Select_Off     unselect entry.
                  MUIV_List_Select_On      select entry.
                  MUIV_List_Select_Toggle  toggle entry.
                  MUIV_List_Select_Ask     just ask about the state.

        state   - Pointer to a longword. If not NULL, this will
                  be filled with the current selection state.

    NOTES
        Since version V9 of muimaster.library: 
        If pos==MUIV_List_Select_All and seltype==MUIV_List_Select_Ask,
        state will be filled with the total number of selected entries.

    EXAMPLE
        /* toggle selection state of active entry */
        DoMethod(list,MUIM_List_Select,MUIV_List_Select_Active,
           MUIV_List_Select_Toggle,NULL);

        /* select all entries */
        DoMethod(list,MUIM_List_Select,MUIV_List_Select_All,
           MUIV_List_Select_On,NULL);

    SEE ALSO
        MUIA_List_MultiTestHook


MUIM_List_Sort


    NAME
        MUIM_List_Sort (V4 )

    SYNOPSIS
        DoMethod(obj,MUIM_List_Sort);

    FUNCTION
        Sort the list. MUI uses an iterative quicksort algorithm,
        no stack problems will occur.

    SEE ALSO
        MUIA_List_CompareHook


MUIM_List_TestPos


    NAME
        MUIM_List_TestPos (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_List_TestPos,LONG x, LONG y, struct MUI_List_TestPos_Result *res);

    FUNCTION
        Find out which line/column of a listview is currently
        displayed at a certain position.





© 1998, Stefan Stuntz [MUI Homepage] [Autodoc Index] [Feedback] Updated: 22-Feb-98