home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 13 / amigaformatcd13.iso / mui / mui_developer / autodocs / mui_list.doc < prev    next >
Text File  |  1997-03-10  |  31KB  |  1,120 lines
  1. TABLE OF CONTENTS
  2.  
  3. List.mui/List.mui
  4. List.mui/MUIA_List_Active
  5. List.mui/MUIA_List_AdjustHeight
  6. List.mui/MUIA_List_AdjustWidth
  7. List.mui/MUIA_List_AutoVisible
  8. List.mui/MUIA_List_CompareHook
  9. List.mui/MUIA_List_ConstructHook
  10. List.mui/MUIA_List_DestructHook
  11. List.mui/MUIA_List_DisplayHook
  12. List.mui/MUIA_List_DragSortable
  13. List.mui/MUIA_List_DropMark
  14. List.mui/MUIA_List_Entries
  15. List.mui/MUIA_List_First
  16. List.mui/MUIA_List_Format
  17. List.mui/MUIA_List_InsertPosition
  18. List.mui/MUIA_List_MinLineHeight
  19. List.mui/MUIA_List_MultiTestHook
  20. List.mui/MUIA_List_Pool
  21. List.mui/MUIA_List_PoolPuddleSize
  22. List.mui/MUIA_List_PoolThreshSize
  23. List.mui/MUIA_List_Quiet
  24. List.mui/MUIA_List_ShowDropMarks
  25. List.mui/MUIA_List_SourceArray
  26. List.mui/MUIA_List_Title
  27. List.mui/MUIA_List_Visible
  28. List.mui/MUIM_List_Clear
  29. List.mui/MUIM_List_CreateImage
  30. List.mui/MUIM_List_DeleteImage
  31. List.mui/MUIM_List_Exchange
  32. List.mui/MUIM_List_GetEntry
  33. List.mui/MUIM_List_Insert
  34. List.mui/MUIM_List_InsertSingle
  35. List.mui/MUIM_List_Jump
  36. List.mui/MUIM_List_Move
  37. List.mui/MUIM_List_NextSelected
  38. List.mui/MUIM_List_Redraw
  39. List.mui/MUIM_List_Remove
  40. List.mui/MUIM_List_Select
  41. List.mui/MUIM_List_Sort
  42. List.mui/MUIM_List_TestPos
  43. List.mui/List.mui
  44.  
  45.     MUI's list class is very powerful. It handles all types
  46.     of entries, from a simple string to a complicated structure
  47.     with many associated resources. Multi column lists are
  48.     also supported, the format for a column is adjustable.
  49.  
  50.     Lists support any kind of sorting, multi selection and
  51.     an active entry that can be controlled with the mouse
  52.     or the cursor keys.
  53.  
  54.     Note: A list object alone doesn't make much sense, you
  55.           should always use it as child of a listview object.
  56.           This one attaches a scrollbar and handles all user
  57.           input.
  58. List.mui/MUIA_List_Active
  59.  
  60.     NAME
  61.     MUIA_List_Active -- (V4 ) [ISG], LONG
  62.  
  63.     SPECIAL INPUTS
  64.     MUIV_List_Active_Off
  65.     MUIV_List_Active_Top
  66.     MUIV_List_Active_Bottom
  67.     MUIV_List_Active_Up
  68.     MUIV_List_Active_Down
  69.     MUIV_List_Active_PageUp
  70.     MUIV_List_Active_PageDown
  71.  
  72.     FUNCTION
  73.     Reading this attribute will return the number of
  74.     the active entry (the one with the cursor on it).
  75.     The result is between 0 and MUIA_List_Entries-1
  76.     or MUIV_List_Active_Off, in which case there is
  77.     currently no active entry.
  78.  
  79.     Setting the attribute will cause the list to
  80.     move the cursor to the new position and scroll
  81.     this position into the visible area.
  82.  
  83.     SEE ALSO
  84.     MUIA_List_Entries, MUIA_List_First, MUIA_List_Visible
  85. List.mui/MUIA_List_AdjustHeight
  86.  
  87.     NAME
  88.     MUIA_List_AdjustHeight -- (V4 ) [I..], BOOL
  89.  
  90.     FUNCTION
  91.     A list with MUIA_List_AdjustHeight set to true is exactly
  92.     as high as all of its entries and not resizable. This is
  93.     only possible when the list is filled *before* the window
  94.     is opened.
  95.  
  96.     SEE ALSO
  97.     MUIA_List_AdjustWidth
  98. List.mui/MUIA_List_AdjustWidth
  99.  
  100.     NAME
  101.     MUIA_List_AdjustWidth -- (V4 ) [I..], BOOL
  102.  
  103.     FUNCTION
  104.     A list with MUIA_List_AdjustWidth set to true is exactly
  105.     as wide as the widest entry and not resizable. This is
  106.     only possible when the list is filled *before* the window
  107.     is opened.
  108.  
  109.     SEE ALSO
  110.     MUIA_List_AdjustHeight
  111. List.mui/MUIA_List_AutoVisible
  112.  
  113.     NAME
  114.     MUIA_List_AutoVisible -- (V11) [ISG], BOOL
  115.  
  116.     FUNCTION
  117.     Set this to make your lists automatically jump to the
  118.     active entry when they are displayed.
  119.  
  120.     SEE ALSO
  121.     MUIA_List_Active
  122. List.mui/MUIA_List_CompareHook
  123.  
  124.     NAME
  125.     MUIA_List_CompareHook -- (V4 ) [IS.], struct Hook *
  126.  
  127.     FUNCTION
  128.     If you plan to have the entries of your list sorted
  129.     (either by inserting them sorted or by using the
  130.     MUIM_List_Sort method) and if the entries of your
  131.     list are not simple strings, you *must* supply
  132.     a compare hook.
  133.  
  134.     This hook will be called with one list element in A1
  135.     and another one in A2. You should return something like
  136.  
  137.     <0   e1 <  e2
  138.      0   e1 == e2
  139.     >0   e1 >  e2
  140.  
  141.     EXAMPLE
  142.     /* the builtin string compare function */
  143.  
  144.         LONG __asm cmpfunc(_a1 char *s1,_a2 char *s2)
  145.     {
  146.        return(stricmp(s1,s2));
  147.     }
  148.  
  149.     SEE ALSO
  150.     MUIA_List_ConstructHook, MUIA_List_DestructHook
  151. List.mui/MUIA_List_ConstructHook
  152.  
  153.     NAME
  154.     MUIA_List_ConstructHook -- (V4 ) [IS.], struct Hook *
  155.  
  156.     SPECIAL INPUTS
  157.     MUIV_List_ConstructHook_String
  158.  
  159.     FUNCTION
  160.     The construct hook is called whenever you add an
  161.     entry to your list. MUI will not insert the given
  162.     pointer directly, but instead call the construct
  163.     hook and add its result code.
  164.  
  165.     Imagine you want to display a list of entries
  166.     in a directory. You could step through it
  167.     using Examine()/ExNext() and directly use the
  168.     MUIM_List_Insert method on your file info block
  169.     buffer.
  170.  
  171.     Your construct hook will be called with this
  172.     file info block as parameter, makes a copy of
  173.     it and returns the address of that copy. Thats
  174.     what is actually added to the list.
  175.  
  176.     The corresponding destruct hook is called whenever
  177.     an entry shall be removed. It's task would simply be
  178.     to free the memory and maybe other resources concering
  179.     this entry that were allocated by the construct hook.
  180.  
  181.     Using these two functions, you will never have to
  182.     worry about freeing the memory used by your list
  183.     entries. Clearing the list or disposing the list
  184.     object will automatically remove all entries and
  185.     thus free the associated resources.
  186.  
  187.     The construct hook will be called with the hook
  188.     in A0, the data given to MUIM_List_Insert as message
  189.     in register A1 and with pointer to a standard kick 3.x
  190.     memory pool in A2. If you want, you can use the exec
  191.     or amiga.lib functions for allocating memory within
  192.     this pool, but this is only an option.
  193.  
  194.     If the construct hook returns NULL, nothing will be
  195.     added to the list.
  196.  
  197.     There is a builtin construct hook available called
  198.     MUIV_List_ConstructHook_String. This expects that
  199.     you only add strings to your list and will make
  200.     a local copy of this string to allow you destroying
  201.     the original. Of course you *must* also use
  202.     MUIV_List_DestructHook_String in this case.
  203.  
  204.     Without construct and destruct hooks, you are responsible
  205.     for allocating and freeing entries yourself.
  206.  
  207.     EXAMPLE
  208.     /* the builtin string construct and destruct functions: */
  209.  
  210.     APTR __asm consfunc(_a2 APTR pool,_a1 char *str)
  211.     {
  212.        char *new;
  213.        if (new=AllocPooled(pool,strlen(str)+1))
  214.           strcpy(new,str);
  215.        return(new);
  216.     }
  217.  
  218.     VOID __asm desfunc(_a2 APTR pool,_a1 char *entry)
  219.     {
  220.        FreePooled(pool,entry,strlen(entry)+1);
  221.     }
  222.  
  223.     /* for more sophisticated hooks see demo program WbMan.c */
  224.  
  225.     SEE ALSO
  226.     MUIA_List_DestructHook, MUIA_List_DisplayHook
  227. List.mui/MUIA_List_DestructHook
  228.  
  229.     NAME
  230.     MUIA_List_DestructHook -- (V4 ) [IS.], struct Hook *
  231.  
  232.     SPECIAL INPUTS
  233.     MUIV_List_DestructHook_String
  234.  
  235.     FUNCTION
  236.     Set up a destruct hook for your list. For detailed
  237.     explanation see MUIA_List_ConstructHook.
  238.  
  239.     SEE ALSO
  240.     MUIA_List_ConstructHook, MUIA_List_DisplayHook
  241. List.mui/MUIA_List_DisplayHook
  242.  
  243.     NAME
  244.     MUIA_List_DisplayHook -- (V4 ) [IS.], struct Hook *
  245.  
  246.     FUNCTION
  247.     Since MUI's lists can handle any kind of entries,
  248.     you have to supply a display hook to specify what
  249.     should actually be shown in the display.
  250.  
  251.     The hook will be called with a pointer to the
  252.     entry to be displayed in A1 and a pointer to
  253.     a string array containing as many entries as
  254.     your list may have columns in A2.
  255.  
  256.     You must fill this array with the strings that
  257.     you want to display.
  258.  
  259.     Note: You can of course use MUI's text engine
  260.           facilities here to create e.g. right aligned
  261.           or centered columns.
  262.  
  263.     Without a display hook, MUI expects a simple one
  264.     columned string list.
  265.  
  266.     See MUIA_List_Format for details about column handling.
  267.  
  268.     Note: Since version 6 of MUI, the display hook also gets the
  269.         position of the current entry as additional parameter. You
  270.     can easily do e.g. some line numbering using this feature. The
  271.     number (from 0 to NumEntries-1) is stored in the longword
  272.     *preceding* the column array (see example below).
  273.  
  274.     EXAMPLE
  275.     /* list of file info blocks, two columned, name and size */
  276.  
  277.     LONG __asm dispfunc(_a2 char **array,_a1 struct FileInfoBlock *fib)
  278.     {
  279.        static char buf1[20],buf2[20];
  280.  
  281.        if (fib->fib_EntryType<0)
  282.          sprintf(buf2,"\33r%ld",fib->fib_Size);
  283.        else
  284.          strcpy(buf2,"\33r(dir)");
  285.  
  286.        sprintf(buf1,"%ld",array[-1]);   // get the line number.
  287.  
  288.        *array++ = buf1;
  289.        *array++ = fib->fib_FileName;
  290.        *array   = buf2;
  291.  
  292.        return(0);
  293.     }
  294.  
  295.     SEE ALSO
  296.     MUIA_List_Format, MUIA_Text_Contents
  297. List.mui/MUIA_List_DragSortable
  298.  
  299.     NAME
  300.     MUIA_List_DragSortable -- (V11) [ISG], BOOL
  301.  
  302.     FUNCTION
  303.     If you set this attribute to TRUE, the user will be able
  304.     to move around entries in the list by using drag&drop.
  305. List.mui/MUIA_List_DropMark
  306.  
  307.     NAME
  308.     MUIA_List_DropMark -- (V11) [..G], LONG
  309.  
  310.     FUNCTION
  311.     After a successfull drop operation, this attribute holds
  312.     the position where we should insert the new entry(ies).
  313.     
  314.     EXAMPLE
  315.     See DragnDrop example program
  316. List.mui/MUIA_List_Entries
  317.  
  318.     NAME
  319.     MUIA_List_Entries -- (V4 ) [..G], LONG
  320.  
  321.     FUNCTION
  322.     Get the current number of entries in the list.
  323.  
  324.     SEE ALSO
  325.     MUIA_List_First, MUIA_List_Visible, MUIA_List_Active
  326. List.mui/MUIA_List_First
  327.  
  328.     NAME
  329.     MUIA_List_First -- (V4 ) [..G], LONG
  330.  
  331.     FUNCTION
  332.     Get the number of the entry displayed on top of
  333.     the list. You have to be prepared to get a result
  334.     of -1, which means that the list is not visible
  335.     at all (e.g. when the window is iconifed).
  336.  
  337.     SEE ALSO
  338.     MUIA_List_Visible, MUIA_List_Entries, MUIA_List_Active
  339. List.mui/MUIA_List_Format
  340.  
  341.     NAME
  342.     MUIA_List_Format -- (V4 ) [ISG], STRPTR
  343.  
  344. 8    FUNCTION
  345.     MUI has the ability to handle multi column lists. To define
  346.     how many columns should be displayed and how they should be
  347.     formatted, you specify a format string.
  348.  
  349.     This format string must contain one entry for each column
  350.     you want to see. Entries are seperated by commas, one
  351.     entry is parsed via dos.library/ReadArgs().
  352.  
  353.     The template for a single entry looks like this:
  354.  
  355.     DELTA=D/N,PREPARSE=P/K,WEIGHT=W/N,
  356.     MINWIDTH=MIW/N,MAXWIDTH=MAW/N,COL=C/N,BAR/S
  357.  
  358.     DELTA
  359.        Space in pixel between this column and the next.
  360.        the last displayed column ignores this setting.
  361.        Defaults to 4.
  362.  
  363.     PREPARSE
  364.        A preparse value for this column. Setting this
  365.        e.g. to "\33c" would make the column centered.
  366.        See MUIA_Text_Contents for other control codes.
  367.  
  368.     WEIGHT
  369.        The weight of the column. As with MUI's group
  370.        class, columns are layouted with a minimum
  371.        size, a maximum size and weight. A column with
  372.        a weight of 200 would gain twice the space than
  373.        a column with a weight of 100.
  374.        Defaults to 100.
  375.  
  376.     MINWIDTH
  377.        Minimum percentage width for the current column.
  378.        If your list is 200 pixel wide and you set this
  379.        to 25, your column will at least be 50 pixel.
  380.        The special value -1 for this parameter means that
  381.        the minimum width is as wide as the widest entry in
  382.        this column. This ensures that every entry will be
  383.        completely visible (as long as the list is wide enough).
  384.        Defaults to -1.
  385.  
  386.     MAXWIDTH
  387.        Maximum percentage width for the current column.
  388.        If your list is 200 pixel wide and you set this
  389.        to 25, your column will not be wider as 50 pixel.
  390.        The special value -1 for this parameter means that
  391.        the maximum width is as wide as the widest entry in
  392.        this column.
  393.        Defaults to -1.
  394.  
  395.     COL
  396.        This value adjusts the number of the current column.
  397.        This allows you to adjust the order of your columns
  398.        without having to change your display hook. See
  399.        example for details.
  400.        Defaults to current entry number (0,1,...)
  401.  
  402.     BAR
  403.        Since muimaster.library V11, you can enable a
  404.        vertical bar between this and the next column by
  405.        using this switch.
  406.  
  407.     If your list object gets so small there is not enough
  408.     place for the minwidth of a column, this column will
  409.     be hidden completely and the remaining space is
  410.     distributed between the remaining columns. This is not
  411.     true if the column is the first column, in this case
  412.     the entries will simply be clipped.
  413.  
  414.     Note: You will have as many columns in your list as
  415.           entries in the format string (i.e. number of
  416.           commas + 1). Empty entries, e.g. with a format
  417.           string of ",,,," are perfectly ok.
  418.  
  419.     The default list format is an empty string (""), this
  420.     means a one column list without special formatting.
  421.  
  422.     BUGS
  423.     Currently there is a maximum of 64 columns for a list.
  424.  
  425.     EXAMPLE
  426.     /* Three column list without further formatting: */
  427.     MUIA_List_Format: ",,"
  428.  
  429.     /* Three column list, middle column centered: */
  430.     MUIA_List_Format: ",P=\33c,"
  431.  
  432.     /* Three column list, display order 2 1 0: */
  433.     MUIA_List_Format: "COL=2,COL=1,COL=0"
  434.  
  435.     /* now something more complex.           */
  436.     /* the display hook defines six entries: */
  437.     dispfunc(_a2 char **array,_a1 struct Article *at)
  438.     {
  439.        *array++ = at->FromName; // col 0
  440.        *array++ = at->FromPath; // col 1
  441.        *array++ = at->ToName;   // col 2
  442.        *array++ = at->ToPath;   // col 3
  443.        *array++ = at->Date;     // col 4
  444.        *array   = at->Subject;  // col 5
  445.     }
  446.  
  447.     /* but we only want to have fromname, date and subject
  448.     /* actually displayed, subject shoud be centered: */
  449.     MUIA_List_Format, "COL=0,COL=4,COL=5 P=\33c"
  450.  
  451.     /* maybe this looks kind of silly, why not make our  */
  452.     /* display hook only fill in these three columns.    */
  453.     /* well, if you would e.g. make the format string    */
  454.     /* user configurable and document what your display  */
  455.     /* hook puts into the array, the user could decide   */
  456.     /* what columns he actually wants to see.            */
  457.     /* The supplied example DFView does something like   */
  458.     /* that.                                             */
  459.  
  460.     /* two column list:   ! Eye    1234 !
  461.                               ! Foot     22 !
  462.                               ! Nose  22331 ! */
  463.  
  464.     MUIA_List_Format, "MAW=100,P=\33r"
  465.  
  466.     SEE ALSO
  467.     MUIA_List_DisplayHook, MUIA_Text_Contents
  468. List.mui/MUIA_List_InsertPosition
  469.  
  470.     NAME
  471.     MUIA_List_InsertPosition -- (V9 ) [..G], LONG
  472.  
  473.     FUNCTION
  474.     After insertion of an element with MUIM_List_Insert,
  475.     you can query the position of the new entry by
  476.     getting this attribute.
  477. List.mui/MUIA_List_MinLineHeight
  478.  
  479.     NAME
  480.     MUIA_List_MinLineHeight -- (V4 ) [I..], LONG
  481.  
  482.     FUNCTION
  483.     Sets the minimum line height for lists in pixels. Useful
  484.     e.g. if you have custom images.
  485. List.mui/MUIA_List_MultiTestHook
  486.  
  487.     NAME
  488.     MUIA_List_MultiTestHook -- (V4 ) [IS.], struct Hook *
  489.  
  490.     FUNCTION
  491.     If you plan to have a multi selecting list but not
  492.     all of your entries are actually multi selectable
  493.     (e.g. in a file requester), you can supply a
  494.     MUIA_List_MultiTestHook.
  495.  
  496.     It will be called with a pointer to an entry in
  497.     A1 and should return TRUE if the entry is multi
  498.     selectable, FALSE otherwise.
  499.  
  500.     EXAMPLE
  501.     /* multi test func for a list of file info blocks */
  502.  
  503.     LONG __asm mtfunc(_a1 struct FileInfoBlock *fib)
  504.     {
  505.        if (fib->fib_DirEntryType<0)
  506.           return(TRUE);
  507.        else
  508.           return(FALSE);
  509.     }
  510.  
  511.     SEE ALSO
  512.     MUIA_List_ConstructHook, MUIA_List_DestructHook
  513. List.mui/MUIA_List_Pool
  514.  
  515.     NAME
  516.     MUIA_List_Pool -- (V13) [I..], APTR
  517.  
  518.     FUNCTION
  519.     Pass something from CreatePool() here if you dont want the list 
  520.     to create its own memory pool but use this one instead. Note 
  521.     that list class does *not* use semaphore protection when 
  522.     accessing the pool, you must *not* use pools which are 
  523.     accessed from different tasks than the applications main
  524.     task.
  525.  
  526.     SEE ALSO
  527.     MUIA_List_PoolPuddleSize, MUIA_List_PoolThreshSize
  528. List.mui/MUIA_List_PoolPuddleSize
  529.  
  530.     NAME
  531.     MUIA_List_PoolPuddleSize -- (V13) [I..], ULONG
  532.  
  533.     FUNCTION
  534.     Specify the puddle size for the lists memory pool.
  535.     Defaults to 2008. Is ignored if you specify your
  536.     own pool with MUIA_List_Pool.
  537.  
  538.     SEE ALSO
  539.     MUIA_List_PoolThreshSize, MUIA_List_Pool
  540. List.mui/MUIA_List_PoolThreshSize
  541.  
  542.     NAME
  543.     MUIA_List_PoolThreshSize -- (V13) [I..], ULONG
  544.  
  545.     FUNCTION
  546.     Specify the thresh size for the lists memory pool.
  547.     Defaults to 1024. Is ignored if you specify your
  548.     own pool with MUIA_List_Pool.
  549.  
  550.     SEE ALSO
  551.     MUIA_List_PoolPuddleSize, MUIA_List_Pool
  552. List.mui/MUIA_List_Quiet
  553.  
  554.     NAME
  555.     MUIA_List_Quiet -- (V4 ) [.S.], BOOL
  556.  
  557.     FUNCTION
  558.     If you add/remove lots of entries to/from a currently visible
  559.     list, this will cause lots of screen action and slow down
  560.     the operation. Setting MUIA_List_Quiet to true will
  561.     temporarily prevent the list from being refreshed, this
  562.     refresh will take place only once when you set it back
  563.     to false again.
  564.  
  565.     EXAMPLE
  566.     set(list,MUIA_List_Quiet,TRUE);
  567.     AddThousandEntries(list);
  568.     set(list,MUIA_List_Quiet,FALSE);
  569.  
  570.     SEE ALSO
  571.     MUIM_List_Insert, MUIM_List_Remove
  572. List.mui/MUIA_List_ShowDropMarks
  573.  
  574.     NAME
  575.     MUIA_List_ShowDropMarks -- (V11) [ISG], BOOL
  576.  
  577.     FUNCTION
  578.     If a list supports Drag & Drop, it usually indicates the place
  579.     where a new line would be inserted with some horizontal lines.
  580.  
  581.     Showing this place doesnt make much sense if you dont care
  582.     about the drop position anyway, e.g. because your list is
  583.     always alphabetically sorted. You should set this attribute
  584.     to FALSE in these cases.
  585.  
  586.     SEE ALSO
  587.     MUIA_List_DropMark
  588. List.mui/MUIA_List_SourceArray
  589.  
  590.     NAME
  591.     MUIA_List_SourceArray -- (V4 ) [I..], APTR
  592.  
  593.     FUNCTION
  594.     The NULL terminated array given here is immediately inserted into the
  595.     list after object creation time.
  596.  
  597.     EXAMPLE
  598.     static const char *KeyList[] =
  599.     {
  600.        "Cursor Up",
  601.        "Cursor Down",
  602.        "Cursor Left",
  603.        "Cursor Right",
  604.        NULL;
  605.     };
  606.  
  607.     LV_Keys = ListviewObject,
  608.        MUIA_Listview_List, ListObject,
  609.           InputListFrame,
  610.           MUIA_List_AdjustWidth, TRUE,
  611.           MUIA_List_SourceArray, KeyList,
  612.           End,
  613.        End;
  614. List.mui/MUIA_List_Title
  615.  
  616.     NAME
  617.     MUIA_List_Title -- (V6 ) [ISG], char *
  618.  
  619.     FUNCTION
  620.     Specify a title for the current list. The title is displayed
  621.     at the very first line and doesn't scroll away when the list
  622.     top position moves.
  623.  
  624.     Usually, the title is just a string. However, if you have
  625.     a multi column list with a custom display hook and you
  626.     want to have seperate titles for each of your columns,
  627.     you can set this attribute to TRUE. In this case, whenever
  628.     MUI feels that the list title has to be drawn, it will
  629.     call your display hook with a NULL entry pointer. Your
  630.     hook has to check for this NULL entry and fill the
  631.     given string array with your column titles. Layout of
  632.     the column titles follows the same rules as layout
  633.     of the lists entries.
  634.  
  635.     EXAMPLE
  636.  
  637.     /* display function for a multi columned file list with titles */
  638.  
  639.     LONG __asm DisplayFunc(_a2 char **array,_a1 struct Entry *e)
  640.     {
  641.        struct Data *data = hook->h_Data;
  642.  
  643.        if (e)
  644.        {
  645.           *array++ = e->Name;
  646.           *array++ = e->Size;
  647.           *array++ = e->Date;
  648.           *array++ = e->Time;
  649.           *array++ = e->Flags;
  650.           *array   = e->Comment;
  651.        }
  652.        else
  653.        {
  654.           *array++ = "Name";
  655.           *array++ = "Size";
  656.           *array++ = "Date";
  657.           *array++ = "Time";
  658.           *array++ = "Flags";
  659.           *array   = "Comment";
  660.        }
  661.  
  662.        return(0);
  663.     }
  664.  
  665.     SEE ALSO
  666.     MUIA_List_DisplayHook
  667. List.mui/MUIA_List_Visible
  668.  
  669.     NAME
  670.     MUIA_List_Visible -- (V4 ) [..G], LONG
  671.  
  672.     FUNCTION
  673.     Get the current number of visible entries in the list.
  674.     You have to be prepared to get a result
  675.     of -1, which means that the list is not visible
  676.     at all (e.g. when the window is iconifed).
  677.  
  678.     SEE ALSO
  679.     MUIA_List_First, MUIA_List_Entries, MUIA_List_Active
  680. List.mui/MUIM_List_Clear
  681.  
  682.     NAME
  683.     MUIM_List_Clear (V4 )
  684.  
  685.     SYNOPSIS
  686.     DoMethod(obj,MUIM_List_Clear);
  687.  
  688.     FUNCTION
  689.     Clear the list, all entries are removed. If a destruct
  690.     hook is set it will be called for every entry.
  691.  
  692.     SEE ALSO
  693.     MUIM_List_Insert, MUIA_List_DestructHook
  694. List.mui/MUIM_List_CreateImage
  695.  
  696.     NAME
  697.     MUIM_List_CreateImage (V11)
  698.  
  699.     SYNOPSIS
  700.     DoMethod(obj,MUIM_List_CreateImage,Object *obj, ULONG flags);
  701.  
  702.     FUNCTION
  703.     If you want to have custom images in a listview (e.g.
  704.     like the little monitor icons in PSI), you should create
  705.     them as Bitmap objects (or Bodychunk objects) in the
  706.     setup method of your list class (use a subclass!). 
  707.  
  708.     After that, pass the newly created object pointer to
  709.     MUIM_List_CreateImage and use the result in your display
  710.     hook with
  711.  
  712.     \33O[%08lx]
  713.  
  714.     where %08lx must be replaced by the pointer you got
  715.     from MUIM_List_CreateImage.
  716.  
  717.     When your list is done (i.e. in the Cleanup method),
  718.     kill your image with MUIM_List_DeleteImage and
  719.     dispose your object.
  720.  
  721.     RESULT
  722.     The result you get is a black box pointer, it's not valid
  723.     to assume anything about it. The only useful thing you can
  724.     do is to include it in \33O[%08lx]. The result may be NULL
  725.     in which case MUI was unable to create the image, but the
  726.     \33O[] combination simply draws nothing when receiving a
  727.     NULL so it shouldnt be considered an error.
  728.  
  729.     EXAMPLE
  730.     See ScreenList class in screen inspector source code psi.c
  731.  
  732.     SEE ALSO
  733.     MUIM_List_DeleteImage
  734. List.mui/MUIM_List_DeleteImage
  735.  
  736.     NAME
  737.     MUIM_List_DeleteImage (V11)
  738.  
  739.     SYNOPSIS
  740.     DoMethod(obj,MUIM_List_DeleteImage,APTR listimg);
  741.  
  742.     FUNCTION
  743.     Delete the image pointer returned from MUIM_List_CreateImage.
  744.  
  745.     SEE ALSO
  746.     MUIM_List_DeleteImage
  747. List.mui/MUIM_List_Exchange
  748.  
  749.     NAME
  750.     MUIM_List_Exchange (V4 )
  751.  
  752.     SYNOPSIS
  753.     DoMethod(obj,MUIM_List_Exchange,LONG pos1, LONG pos2);
  754.  
  755.     FUNCTION
  756.     Exchange two entries in a list.
  757.  
  758.     INPUTS
  759.     pos1 - number of the first entry.
  760.     pos2 - number of the second entry.
  761.  
  762.     Possible special values since muimaster.library V9:
  763.  
  764.     MUIV_List_Exchange_Top       0
  765.     MUIV_List_Exchange_Active   -1
  766.     MUIV_List_Exchange_Bottom   -2
  767.     MUIV_List_Exchange_Next     -3 /* only valid for second parameter */
  768.     MUIV_List_Exchange_Previous -4 /* only valid for second parameter */
  769.  
  770.     SEE ALSO
  771.     MUIM_List_Insert, MUIM_List_Remove, MUIM_List_Move
  772. List.mui/MUIM_List_GetEntry
  773.  
  774.     NAME
  775.     MUIM_List_GetEntry (V4 )
  776.  
  777.     SYNOPSIS
  778.     DoMethod(obj,MUIM_List_GetEntry,LONG pos, APTR *entry);
  779.  
  780.     FUNCTION
  781.     Get an entry of a list.
  782.  
  783.     INPUTS
  784.     pos   - Number of entry, MUIV_List_GetEntry_Active can
  785.             be used to get the active entry.
  786.  
  787.     entry - Pointer to a longword where the entry will
  788.             be stored. If the entry is not available
  789.             (either because you are out of bounds or
  790.             because there is no active entry), you will
  791.             receive a NULL.
  792.  
  793.     EXAMPLE
  794.     /* iterate through a list containing file info blocks */
  795.  
  796.     for (i=0;;i++)
  797.     {
  798.         struct FileInfoBlock *fib;
  799.  
  800.         DoMethod(list,MUIM_List_GetEntry,i,&fib);
  801.         if (!fib) break;
  802.  
  803.         printf("%s\n",fib->fib_FileName);
  804.     }
  805.  
  806.     SEE ALSO
  807.     MUIM_List_Insert, MUIM_List_Remove
  808. List.mui/MUIM_List_Insert
  809.  
  810.     NAME
  811.     MUIM_List_Insert (V4 )
  812.  
  813.     SYNOPSIS
  814.     DoMethod(obj,MUIM_List_Insert,APTR *entries, LONG count, LONG pos);
  815.  
  816.     FUNCTION
  817.     Insert new entries into a list.
  818.     When the list has a construct hook, the given pointers
  819.     won't be inserted directly but instead passed through 
  820.     to the construct hook.
  821.  
  822.     INPUTS
  823.     entries - pointer to an array of pointers to be inserted.
  824.               Warning: This is a pointer to a pointer. See
  825.               example for details.
  826.  
  827.     count   - Number of elements to be inserted. If count==-1,
  828.               entries will be inserted until NULL pointer in
  829.               the entries array is found.
  830.  
  831.     pos     - New entries will be added in front of this entry.
  832.               MUIV_List_Insert_Top:
  833.                  insert as first entry.
  834.               MUIV_List_Insert_Active:
  835.                  insert in front of the active entry.
  836.               MUIV_List_Insert_Sorted:
  837.                  insert sorted.
  838.               MUIV_List_Insert_Bottom:
  839.                  insert as last entry.
  840.  
  841.               If pos is bigger or equal to the number of entries
  842.               in the list, it's treated like MUIV_List_Insert_Bottom.
  843.  
  844.     EXAMPLE
  845.     /* insert a string */
  846.     char *str = "New entry";
  847.     DoMethod(list,MUIM_List_Insert,&str,1,MUIV_List_Insert_Bottom);
  848.  
  849.     /* insert an array */
  850.     char *str[] =
  851.     {
  852.        "Entry 1",
  853.        "Entry 2",
  854.        "Entry 3",
  855.        "Entry 4",
  856.        NULL
  857.     };
  858.     DoMethod(list,MUIM_List_Insert,str,-1,MUIV_List_Insert_Bottom);
  859.  
  860.     SEE ALSO
  861.     MUIM_List_Remove, MUIA_List_ConstructHook
  862. List.mui/MUIM_List_InsertSingle
  863.  
  864.     NAME
  865.     MUIM_List_InsertSingle (V7 )
  866.  
  867.     SYNOPSIS
  868.     DoMethod(obj,MUIM_List_InsertSingle,APTR entry, LONG pos);
  869.  
  870.     FUNCTION
  871.     Insert one new entry into a list. Using MUIM_List_Insert has
  872.     caused some confusion since it takes an array to items instead
  873.     a single item. To insert single items, MUIM_List_InsertSingle
  874.     is the better choice.
  875.  
  876.     When the list has a construct hook, the given pointer
  877.     won't be inserted directly but instead passed through
  878.     to the construct hook.
  879.  
  880.     INPUTS
  881.     entry   - item to insert.
  882.  
  883.     pos     - New entry will be added in front of this entry.
  884.               MUIV_List_Insert_Top:
  885.                  insert as first entry.
  886.               MUIV_List_Insert_Active:
  887.                  insert in front of the active entry.
  888.               MUIV_List_Insert_Sorted:
  889.                  insert sorted.
  890.               MUIV_List_Insert_Bottom:
  891.                  insert as last entry.
  892.  
  893.               If pos is bigger or equal to the number of entries
  894.               in the list, it's treated like MUIV_List_Insert_Bottom.
  895.  
  896.     EXAMPLE
  897.     /* insert a string */
  898.     DoMethod(list,MUIM_List_InsertSingle,"foobar",MUIV_List_Insert_Bottom);
  899.  
  900.     SEE ALSO
  901.     MUIM_List_Remove, MUIA_List_ConstructHook, MUIM_List_InsertSingle
  902. List.mui/MUIM_List_Jump
  903.  
  904.     NAME
  905.     MUIM_List_Jump (V4 )
  906.  
  907.     SYNOPSIS
  908.     DoMethod(obj,MUIM_List_Jump,LONG pos);
  909.  
  910.     FUNCTION
  911.     Scroll any entry into the visible part of a list.
  912.  
  913.     Note: Jumping to an entry doesn't mean to make this
  914.           entry the active one. This can be done by 
  915.           setting the MUIA_List_Active attribute.
  916.  
  917.     INPUTS
  918.     pos - Number of the entry that should be made visible.
  919.           Use MUIV_List_Jump_Active to jump to the active
  920.           entry.
  921.  
  922.     EXAMPLE
  923.     /* line 42 is interesting, so make it visible */
  924.     DoMethod(list,MUIM_List_Jump,42);
  925.  
  926.     SEE ALSO
  927.     MUIA_List_Active
  928. List.mui/MUIM_List_Move
  929.  
  930.     NAME
  931.     MUIM_List_Move (V9 )
  932.  
  933.     SYNOPSIS
  934.     DoMethod(obj,MUIM_List_Move,LONG from, LONG to);
  935.  
  936.     FUNCTION
  937.     Move an entry from one position to another.
  938.  
  939.     INPUTS
  940.     pos1 - number of the first entry.
  941.     pos2 - number of the second entry.
  942.  
  943.     Possible special values since muimaster.library V9:
  944.  
  945.     MUIV_List_Move_Top       0
  946.     MUIV_List_Move_Active   -1
  947.     MUIV_List_Move_Bottom   -2
  948.     MUIV_List_Move_Next     -3 /* only valid for second parameter */
  949.     MUIV_List_Move_Previous -4 /* only valid for second parameter */
  950.  
  951.     SEE ALSO
  952.     MUIM_List_Insert, MUIM_List_Remove, MUIM_List_Exchange
  953. List.mui/MUIM_List_NextSelected
  954.  
  955.     NAME
  956.     MUIM_List_NextSelected (V6 )
  957.  
  958.     SYNOPSIS
  959.     DoMethod(obj,MUIM_List_NextSelected,LONG *pos);
  960.  
  961.     FUNCTION
  962.     Iterate through the selected entries of a list.
  963.     This method steps through the contents of a (multi
  964.     select) list and returns every entry that is currently
  965.     selected. When no entry is selected but an entry is
  966.     active, only the active entry will be returned.
  967.  
  968.     This behaviour will result in not returning the
  969.     active entry when you have some other selected
  970.     entries somewhere in your list. Since the active
  971.     entry just acts as some kind of cursor mark,
  972.     this seems to be the only sensible possibility
  973.     to handle multi selection together with keyboard
  974.     control.
  975.  
  976.     INPUTS
  977.     pos - a pointer to longword that will hold the number
  978.           of the returned entry. Must be set to 
  979.           MUIV_List_NextSelected_Start at start of iteration. 
  980.           Is set to MUIV_List_NextSelected_End when iteration
  981.           is finished.
  982.  
  983.     EXAMPLE
  984.  
  985.     /* Iterate through a list with FileInfoBlocks */
  986.  
  987.     struct FileInfoBlock *fib;
  988.     LONG id = MUIV_List_NextSelected_Start;
  989.  
  990.     for (;;)
  991.     {
  992.        DoMethod(list,MUIM_List_NextSelected,&id);
  993.        if (id==MUIV_List_NextSelected_End) break;
  994.  
  995.        DoMethod(list,MUIM_List_GetEntry,id,&fib);
  996.        printf("selected: %s\n",fib->fib_FileName);
  997.     }
  998.  
  999.  
  1000.     SEE ALSO
  1001.     MUIM_List_Select
  1002. List.mui/MUIM_List_Redraw
  1003.  
  1004.     NAME
  1005.     MUIM_List_Redraw (V4 )
  1006.  
  1007.     SYNOPSIS
  1008.     DoMethod(obj,MUIM_List_Redraw,LONG pos);
  1009.  
  1010.     FUNCTION
  1011.     If you made some changes to an entry of your list and
  1012.     want these changes to be shown in the display, you will
  1013.     have to call this method.
  1014.  
  1015.     INPUTS
  1016.     pos - Number of the line to redraw. When the line is not
  1017.           currently visible, nothing will happen. Specials:
  1018.           MUIV_List_Redraw_Active:
  1019.              redraw the active line (if any),
  1020.           MUIV_List_Redraw_All:
  1021.              redraw all lines.
  1022.  
  1023.     EXAMPLE
  1024.     /* do a complete refresh: */
  1025.     DoMethod(list,MUIM_List_Redraw,MUIV_List_Redraw_All);
  1026. List.mui/MUIM_List_Remove
  1027.  
  1028.     NAME
  1029.     MUIM_List_Remove (V4 )
  1030.  
  1031.     SYNOPSIS
  1032.     DoMethod(obj,MUIM_List_Remove,LONG pos);
  1033.  
  1034.     FUNCTION
  1035.     Remove an entry from a list.
  1036.  
  1037.     INPUTS
  1038.     pos - number of the entry to be removed or one of
  1039.           MUIV_List_Remove_First,
  1040.           MUIV_List_Remove_Active,
  1041.           MUIV_List_Remove_Last.
  1042.               MUIV_List_Remove_Selected.
  1043.           When the active entry is removed, the following entry
  1044.           will become active.
  1045.  
  1046.     EXAMPLE
  1047.     /* when delete is pressed, remove the active entry */
  1048.     DoMethod(btdel,MUIM_Notify,MUIA_Pressed,FALSE,
  1049.        list,2,MUIM_List_Remove,MUIV_List_Remove_Active);
  1050.  
  1051.     SEE ALSO
  1052.     MUIM_List_Insert, MUIA_List_DestructHook
  1053. List.mui/MUIM_List_Select
  1054.  
  1055.     NAME
  1056.     MUIM_List_Select (V4 )
  1057.  
  1058.     SYNOPSIS
  1059.     DoMethod(obj,MUIM_List_Select,LONG pos, LONG seltype, LONG *state);
  1060.  
  1061.     FUNCTION
  1062.     Select/deselect a list entry or ask an entry if its
  1063.     selected.
  1064.  
  1065.     INPUTS
  1066.  
  1067.     pos     - Number of the entry or
  1068.               MUIV_List_Select_Active for the active entry.
  1069.               MUIV_List_Select_All    for all entries.
  1070.  
  1071.     seltype - MUIV_List_Select_Off     unselect entry.
  1072.               MUIV_List_Select_On      select entry.
  1073.               MUIV_List_Select_Toggle  toggle entry.
  1074.               MUIV_List_Select_Ask     just ask about the state.
  1075.  
  1076.     state   - Pointer to a longword. If not NULL, this will
  1077.               be filled with the current selection state.
  1078.  
  1079.     NOTES
  1080.     Since version V9 of muimaster.library: 
  1081.     If pos==MUIV_List_Select_All and seltype==MUIV_List_Select_Ask,
  1082.     state will be filled with the total number of selected entries.
  1083.  
  1084.     EXAMPLE
  1085.     /* toggle selection state of active entry */
  1086.     DoMethod(list,MUIM_List_Select,MUIV_List_Select_Active,
  1087.        MUIV_List_Select_Toggle,NULL);
  1088.  
  1089.     /* select all entries */
  1090.     DoMethod(list,MUIM_List_Select,MUIV_List_Select_All,
  1091.        MUIV_List_Select_On,NULL);
  1092.  
  1093.     SEE ALSO
  1094.     MUIA_List_MultiTestHook
  1095. List.mui/MUIM_List_Sort
  1096.  
  1097.     NAME
  1098.     MUIM_List_Sort (V4 )
  1099.  
  1100.     SYNOPSIS
  1101.     DoMethod(obj,MUIM_List_Sort);
  1102.  
  1103.     FUNCTION
  1104.     Sort the list. MUI uses an iterative quicksort algorithm,
  1105.     no stack problems will occur.
  1106.  
  1107.     SEE ALSO
  1108.     MUIA_List_CompareHook
  1109. List.mui/MUIM_List_TestPos
  1110.  
  1111.     NAME
  1112.     MUIM_List_TestPos (V11)
  1113.  
  1114.     SYNOPSIS
  1115.     DoMethod(obj,MUIM_List_TestPos,LONG x, LONG y, struct MUI_List_TestPos_Result *res);
  1116.  
  1117.     FUNCTION
  1118.     Find out which line/column of a listview is currently
  1119.     displayed at a certain position.
  1120.