Graphics Plus/Graphics Plus.iso/amiga/gui/mui/mui14-dv.lha/MUI/Developer/Autodocs/MUI_List.doc

Text File | 1993-10-28 | 20.1 KB | 765 lines

TABLE OF CONTENTS

List.mui/List.mui
List.mui/MUIM_List_Clear
List.mui/MUIM_List_Exchange
List.mui/MUIM_List_GetEntry
List.mui/MUIM_List_Insert
List.mui/MUIM_List_Jump
List.mui/MUIM_List_NextSelected
List.mui/MUIM_List_Redraw
List.mui/MUIM_List_Remove
List.mui/MUIM_List_Select
List.mui/MUIM_List_Sort
List.mui/MUIA_List_Active
List.mui/MUIA_List_AdjustHeight
List.mui/MUIA_List_AdjustWidth
List.mui/MUIA_List_CompareHook
List.mui/MUIA_List_ConstructHook
List.mui/MUIA_List_DestructHook
List.mui/MUIA_List_DisplayHook
List.mui/MUIA_List_Entries
List.mui/MUIA_List_First
List.mui/MUIA_List_Format
List.mui/MUIA_List_MultiTestHook
List.mui/MUIA_List_Quiet
List.mui/MUIA_List_Visible
List.mui/List.mui

    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/MUIM_List_Clear

    NAME
    MUIM_List_Clear

    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
List.mui/MUIM_List_Exchange

    NAME
    MUIM_List_Exchange

    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.

    MUIV_List_Exchange_Active for pos1 or pos2
    addresses the currently active entry.

    SEE ALSO
    MUIM_List_Insert, MUIA_List_Remove
List.mui/MUIM_List_GetEntry

    NAME
    MUIM_List_GetEntry

    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
List.mui/MUIM_List_Insert

    NAME
    MUIM_List_Insert

    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.

    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
List.mui/MUIM_List_Jump

    NAME
    MUIM_List_Jump

    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
List.mui/MUIM_List_NextSelected

    NAME
    MUIM_List_NextSelected

    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 -1 at
          start of iteration. Is set to -1 when iteration
          is finished.

    EXAMPLE

    /* Iterate through a list with FileInfoBlocks */

    struct FileInfoBlock *fib;
    LONG id = -1;

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

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


    SEE ALSO
    MUIM_List_Select
List.mui/MUIM_List_Redraw

    NAME
    MUIM_List_Redraw

    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);
List.mui/MUIM_List_Remove

    NAME
    MUIM_List_Remove

    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.
          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
List.mui/MUIM_List_Select

    NAME
    MUIM_List_Select

    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.

    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.

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

    SEE ALSO
    MUIA_List_MultiTest_Hook
List.mui/MUIM_List_Sort

    NAME
    MUIM_List_Sort

    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
List.mui/MUIA_List_Active

    NAME
    MUIA_List_Active -- [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
List.mui/MUIA_List_AdjustHeight

    NAME
    MUIA_List_AdjustHeight -- [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
List.mui/MUIA_List_AdjustWidth

    NAME
    MUIA_List_AdjustWidth -- [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
List.mui/MUIA_List_CompareHook

    NAME
    MUIA_List_CompareHook -- [I..], 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

    -1   e1 <  e2
     0   e1 == e2
     1á  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
List.mui/MUIA_List_ConstructHook

    NAME
    MUIA_List_ConstructHook -- [I..], 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
List.mui/MUIA_List_DestructHook

    NAME
    MUIA_List_DestructHook -- [I..], 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
List.mui/MUIA_List_DisplayHook

    NAME
    MUIA_List_DisplayHook -- [I..], 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
List.mui/MUIA_List_Entries

    NAME
    MUIA_List_Entries -- [..G], LONG

    FUNCTION
    Get the current number of entries in the list.

    SEE ALSO
    MUIA_List_First, MUIA_List_Visible, MUIA_List_Active
List.mui/MUIA_List_First

    NAME
    MUIA_List_First -- [..G], LONG

    FUNCTION
    Get the number of the entry displayed on top of
    the list.

    SEE ALSO
    MUIA_List_Visible, MUIA_List_Entries, MUIA_List_Active
List.mui/MUIA_List_Format

    NAME
    MUIA_List_Format -- [ISG], STRPTR

    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

    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,...)

    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. 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
List.mui/MUIA_List_MultiTestHook

    NAME
    MUIA_List_MultiTestHook -- [I..], 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
List.mui/MUIA_List_Quiet

    NAME
    MUIA_List_Quiet -- [.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
List.mui/MUIA_List_Visible

    NAME
    MUIA_List_Visible -- [..G], LONG

    FUNCTION
    Get the current number of visible entries in the list.
    This attribute is propably not of much use.

    SEE ALSO
    MUIA_List_First, MUIA_List_Entries, MUIA_List_Active