Amiga ISO Collection

home *** CD-ROM | disk | FTP | other *** search

/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / bgui.lzx / bgui / docs / listviewclass.doc < prev next >

Wrap

Text File | 1995-05-18 | 32.3 KB | 829 lines

File: listviewclass.doc Description: Listviewclass documentation. Copyright: (C) Copyright 1994-1995 Jaba Development. (C) Copyright 1994-1995 Jan van den Baard. All Rights Reserved. ------------------------------------------------------------------------------ TABLE OF CONTENTS listviewclass/--background-- listviewclass/Methods listviewclass/Attributes listviewclass/--background-- listviewclass/--background-- NAME Class: listviewclass Superclass: baseclass Include File: <libraries/bgui.h> FUNCTION To provide a gadget simular to the gadtools.library it's listview kind. The lisview class does how ever have extended functionality like hooks for entry creation, entry comparrison, entry and title rendering. Also a multi-selection mode is available. Opposed to the gadtools version this class does not require the usage of list and nodes. All kind of data can be added to the listview as entries providing that you supply hook routines to handle this data. Objects from this class send out the following attribute pairs in their notification events: GA_ID - Gadget object ID. LISTV_Entry - Pointer to the selected entry. LISTV_EntryNumber - Logical number of the selected entry. listviewclass/Methods listviewclass/Methods NOTE Most of the methods described below can also contain a pointer to a GadgetInfo structure. This pointer does not have to be valid. All actions will be done only if you want to let the action also be shown visually you need to pass a valid pointer to a GadgetInfo structure. NEW METHODS LVM_ADDENTRIES -- This method can be used to add more than one entry after the listview object has been created. It uses the following custom message structure: struct lvmAddEntries { ULONG MethodID; /* LVM_ADDENTRIES */ struct GadgetInfo *lvmaGInfo; /* See note above. */ APTR *lvma_Entries; ULONG lvma_How; }; lvma_Entries -- This must point to a NULL-terminated array of pointers to the entries to add. lvma_How -- Here you can select where the entries are added. The following positions are possible: LVAP_HEAD -- The entries are added at the top of the list. LVAP_TAIL -- The entries are added at the bottom of the list. LVAP_SORTED -- The entries are added sorted according to the sorting method active. In the attributes section of this documentation you can find more about the sorting possibilities. This method returns TRUE uppon succes and FALSE if one or more of the entries failed to be added. LVM_ADDSINGLE -- This method can be used to add a single entry to the listview object after it has been created. It uses the following custom message structure: struct lvmAddSingle { ULONG MethodID; /* LVM_ADDSINGLE */ struct GadgetInfo *lvma_GInfo; /* See note above. */ APTR lvma_Entry; ULONG lvma_How; ULONG lvma_Flags; }; lvma_Entry -- This must point to the entry which needs to be added to the listview object. lvma_How -- Please refer to the LVM_ADDENTRIES section for more information on the ways you can add entries. lvma_Flags -- Any of the following flags can be set here: LVASF_MAKEVISIBLE -- This tell's the lisview object to scroll the list to make the added entry visible. LVASF_SELECT -- This tell's the listview object to make the added entry selected. This will also automatically scroll the list to make the added entry visible. Returns TRUE uppon success, FALSE uppon failure. LVM_CLEAR -- This method must be used to clear and delete all entries present in the list. It uses the following custom message structure: struct lvmCommand { ULONG MethodID; /* Several */ struct GadgetInfo *lvmc_GInfo; /* See note above. */ }; Return code is not defined. LVM_FIRSTENTRY, LVM_LASTENTRY, LVM_NEXTENTRY, LVM_PREVENTRY -- These methods must be used to itterate through all entries in the listview. All these methods use the following message structure: struct lvmGetEntry { ULONG MethodID; /* Any of the above. */ APTR lvmg_Previous; ULONG lvmg_Flags; }; lvmg_Previous -- For the LVM_FIRSTENTRY and LVM_LASTENTRY methods this must be NULL. For the LVM_NEXTENTRY and LVM_PREVENTRY this should point to the entry returned by a previous call to any of these methods. lvmg_Flags -- Any of the following flags may be set here: LVGEF_SELECTED -- The methods will only scan for selected entries when this bit is set. All non-selected entries will simply be skipped. Returns a pointer to the entry or NULL when no more entries are available. Example: /* ** Scan through all entries in ** the listview gadget starting ** at the first one. **/ Object *listview; APTR entry; /* ** Get first entry. **/ if ( entry = (APTR)DoMethod( listview, LVM_FIRSTENTRY, NULL, 0L )) { /* ** Loop through the rest of the list. **/ do { /* ** Print the entry... **/ printf( "Entry = %s\n", entry ); /* ** Next entry... **/ entry = (APTR)DoMethod( listview, LVM_NEXTENTRY, entry, 0L ); } while ( entry ); } LVM_REMENTRY -- This method must be used to remove a single entry from the listview object. It uses the following custom message structure: struct lvmRemEntry { ULONG MethodID; /* LVM_REMENTRY */ struct GadgetInfo *lvmr_GInfo; /* See note above. */ APTR lvmr_Entry; }; lvmr_Entry -- This must point to the entry you want to remove. This usually is a pointer returned to you by either the LVM_FIRSTENTRY, LVM_LASTENTRY, LVM_NEXTENTRY or LVM_PREVENTRY method. Return code is not defined. LVM_REFRESH -- This method must be used to refresh the listview object after some changes have been made which where not visible. In some cases it might be usefull to add entries without passing a GadgetInfo structure along with the adding methods. This will speed up the adding and you can show the changes when you are done by sending this method to the listview object. This method uses the same custom message structure as defined above at the LVM_CLEAR method. Return code is not defined. LVM_SORT -- Calling this method will force a complete re-sorting of the entries in the list. This can be handy when your comparisson hook (described in the Attributes section) can handle different kinds of comparissons. This method uses the same custom message structure as defined above at the LVM_CLEAR method. Return code is not defined. LVM_LOCKLIST, LVM_UNLOCKLIST -- These methods must be used to lock or unlock the list contents. When, for example, you must change the text of a list entry you should lock it using the LVM_LOCKLIST method and when you are done unlock it using the LVM_UNLOCKLIST method. This locking is necessary while the list may get referenced while you are doing your changes. Both methods use the same custom message structure as defined above at the LVM_CLEAR method. LVM_MOVE ** V38 ** -- This method must be used to move entries in the list. This method uses the following custom message structure: struct lvmMove { ULONG MethodID; /* LVM_MOVE */ struct GadgetInfo *lvmm_GInfo; /* GadgetInfo */ APTR lvmm_Entry; ULONG lvmm_Direction; }; lvmm_Entry -- This can point to the specific entry you want to move. If you specify NULL here the selected entry is moved. lvmm_Direction -- Here you can specify the direction in which the entry must be moved. The following directions are possible: LVMOVE_UP -- Move the entry one place up. LVMOVE_DOWN -- Move the entry one place down. LVMOVE_TOP -- Move the entry to the list-top. LVMOVE_BOTTOM -- Move the entry to the list-bottom. When the entry actually moved the class will send out a notification message with the following attributes: GA_ID -- The ID of the object. LISTV_NewPosition -- The new numeric position of the entry. Returns TRUE when the entry moved and FALSE if not. LVM_REPLACE ** V39 ** -- This method allows you to replace an existing entry with another. This method uses the following custom message structure: struct lvmReplace { ULONG MethodID; /* LVM_REPLACE */ struct GadgetInfo *lvmr_GInfo; /* GadgetInfo */ APTR lvmr_OldEntry; APTR lvmr_NewEntry; }; lvmr_OldEntry -- This must be a pointer to the entry you want to replace. lvmr_NewEntry -- This must point to the new data you want to replace the old entry by. Returns the new eentry uppon success and NULL uppon failure. CHANGED METHODS None. listviewclass/Attributes listviewclass/Attributes NAME LISTV_ResourceHook -- ( struct Hook * ) FUNCTION To add a hook routine that will build or delete a listview entry. The hook routine will be called as follows: rc = hookFunc( hook, object, message ); D0 A0 A2 A1 APTR rc; struct Hook *hook; Object *object; struct lvRender *message; The message arguments is a pointer to the following data structure: struct lvResource { UWORD lvr_Command; APTR lvr_Entry; }; lvr_Command -- This can be LVRC_MAKE which means that the hook should create an entry or it can be LVRC_KILL which means that the hook must dispose of a previously created entry. lvr_Entry -- When this is a LVRC_MAKE command this contains the data added to the listview by one of the adding methods or attributes. When this is a LVRC_KILL command this points to whatever LVRC_MAKE has created. The default creating/deletion that is done by the listview expects the entries to be simple string pointers. Internally these strings are copied to an internal buffer when the entry is created. When the entry is disposed of the string copy is simply de-allocated. If you add entries to the listview which are not string pointers you must supply your own resource handling using this attribute. Example: /* ** This example takes a PubScreenNode as input, ** copies the name and adds that to the listview. ** Uppon deletion it simply de-allocates the copy ** of the string. **/ __saveds __asm APTR hookFunc( register __a0 struct Hook *hook, register __a2 Object *object, register __a1 struct lvResource *lvr ) { struct PubScreenNode *psn = ( struct PubScreenNode * )lvr->lvr_Entry; UWORD len; APTR rc = NULL; /* ** Built or dispose? **/ switch ( lvr->lvr_Command ) { case LVRC_MAKE: /* ** Determine string size. **/ len = strlen( psn->psn_Node.ln_name ) + 1; /* ** Allocate and copy the string. **/ if ( rc = ( APTR )AllocVec( len, MEMF_ANY )) strcpy(( UBYTE * )rc, psn->psn_Node.ln_Name ); break; case LVRC_KILL: /* ** Simply de-allocate whats created above. **/ FreeVec( lvr->lvr_Entry ); break; } /* ** 'rc' will be a pointer to the created ** string copy or NULL which indicates a ** memory error with LVRC_MAKE. If rc is non-NULL ** the string is added to the list of entries. **/ return( rc ); } The hook must return a pointer to the data created when the command is LVRC_MAKE. When the command is LVRC_MAKE and NULL is returned the entry will not be added to the list. LVRC_KILL commands do not have a return code defined. Default is NULL (internal memory handling). Applicability is (I). SEE ALSO LISTV_DisplayHook, LISTV_CompareHook NAME LISTV_DisplayHook -- ( struct Hook * ) FUNCTION To add a hook routine that will take care of rendering the entries. In some cases it is necessary to do your own rendering. This hook is called for each entry that needs to be rendered. The hook routine will be called as follows: rc = hookFunc( hook, object, message ); D0 A0 A2 A1 VOID rc; /* No return code defined. */ struct Hook *hook; Object *object; struct lvRender *message; The message argument is a pointer to the following data structure: struct lvRender { struct RastPort *lvr_RPort; struct DrawInfo *lvr_DrawInfo; struct Rectangle *lvr_Bounds; APTR lvr_Entry; UWORD lvr_State; UWORD lvr_Flags; }; lvr_RPort -- This is a pointer to the RastPort in which the rendering must be done. Please note that the font you must use to render text is already set up for you. It is not recommendable to use another font than the one set in this RastPort because the height of the area you may render in is setup accoording to this font. lvr_DrawInfo -- This can point to a DrawInfo structure as defined in <intuition/screens.h> in which the necessay information about the display environment is stored. Note that it is possible that this is NULL. It is not very likely but it is possible. lvr_Bounds -- This is a struct Rectangle in which the area you should render in is defined. Do _not_ render outside the given bounds or you will seriously screw up the display! Also keep in mind that the area you are rendering into is not always cleared. In other words, the area may still show data from another entry. You must make sure you completely re-render the given bounds. lvr_Entry -- This points to the entry data as setup by the entry creation hook or the built-in entry creation. lvr_State -- This describes the state in which to render the entry. The state is one of the following possibilities: LVRS_NORMAL -- Normal rendering. Render the entry in a normal, un-selected way. LVRS_SELECTED -- Selected rendering. Render the entry in a selected way. LVRS_NORMAL_DISABLED -- Normal, disabled rendering. Render the entry in a normal way but make it disabled. This is normally done by ghosting it with a pattern (see below). LVRS_SELECTED_DISABLED -- Selected, disabled rendering. Render the entry is a selected way but make it disabled. This is normally done by ghosting it with a pattern (see below). Ghosting the entry is usually done like this: struct lvRender *lvr; UWORD *pens = lvr->lvr_DrawInfo->dri_Pens; UWORD patt = { 0x2222, 0x8888 }; SetAPen( lvr->lvr_RPort, pens[ SHADOWPEN ] ); SetDrMd( lvr->lvr_RPort, JAM1 ); SetAfPt( lvr->lvr_RPort, patt, 1 ); RectFill( lvr->lvr_RPort, lvr->lvr_Bounds.MinX, lvr->lvr_Bounds.MinY, lvr->lvr_Bounds.MaxX, lvr->lvr_Bounds.MaxY ); Please keep in mind that, although the above code doesn't show it, the lvr_DrawInfo field can be NULL. lvr_Flags -- No flags are defined yet. When this hook is not set the internal rendering routine will simply render a string which is created in the LIST_ResourceHook. When the LISTV_RenderHook routine creates something other than a simple string pointer you must provide a display hook to render the entries. Most of the time when you add more than a simple string to the listview object the data you add is a structure which contains the string and some extra data. To prevent you from having to write a display-hook to render the string your hook can also simply return a pointer to the string and the listviewclass will render it for you. I.E.: struct myStruct { UBYTE *string; UWORD some_more_data; }; __saveds __asm hookFunc( register __a0 struct Hook *hook, register __a2 Object *lv_obj, register __a1 struct lvRender *lvr ) { return((( struct myNode * )lvr->lvr_Entry )->string ); } This hook will let the listviewclass dispatcher render the returned string for you while keeping the extended data available for you. If your hook returns NULL the listviewclass assumes you have done all rendering required. Default is NULL (internal entry rendering). Applicability is (I). SEE ALSO LISTV_ResourceHook, LISTV_CompareHook, LISTV_TitleHook NAME LISTV_CompareHook -- ( struct Hook * ) FUNCTION To add a hook routine that will compare two entries with eachother. As it is possible to have entries which are different from simple strings you can perform your own comparison here. The comparison hook is called each time an entry is added sorted or when the list is re- sorted. The hook routine will be called as follows: rc = hookFunc( hook, object, message ); D0 A0 A2 A1 LONG rc; struct Hook *hook; Object *object; struct lvCompare *message; The message argument is a pointer to the following data structure: struct lvCompare { APTR lvc_EntryA; APTR lvc_EntryB; }; lvc_EntryA, lvc_EntryB -- These are the entries that must be compared to eachother. The internal comparison routine simple does a stricmp() on the two entry strings. This hook must return -1 when entry a is smaller than entry b, 0 when entry a is equal to entry b and 1 when entry a is bigger than entry b. Default is NULL (internal comparison routine). Applicability is (I). SEE ALSO LISTV_ResourceHook, LISTV_DisplayHook NAME LISTV_Top -- ( ULONG ) FUNCTION Set the top-entry of the visible part of the list. This tag is mostly used by the prop object that is connected to the listview but it can also be controlled by your program. The data of this tag must be the number of the node to set at the top of the visible area. Default is 0. Applicability is (ISGU). NAME LISTV_ListFont -- ( struct TextAttr ) FUNCTION To set the font which is used to render the entries. By default the font used to render the entries is the same font which is used to render the object it's label. This font might be proportional. In some cases it might be useful to have a mono-space font for the entries or even another proportional font. Default is NULL. Applicability is (IG) NAME LISTV_ReadOnly -- ( BOOL ) FUNCTION To make the listview a read-only object. Read only objects have full functionality except for the entries which cannot be selected. Default is FALSE. Applicability is (I). NAME LISTV_MultiSelect -- ( BOOL ) FUNCTION To make the listview a multi-selection object. Multi-selection objects allow the user to select more than one entry from the list. Default is FALSE. Applicability is (ISU). NAME LISTV_EntryArray -- ( APTR * ) FUNCTION To add a set of entries at initialization time. The data is a pointer to a NULL-terminated array of entries which need to be added to the listview object. Default is NULL. Applicability is (I). SEE ALSO LISTV_SortEntryArray NAME LISTV_SortEntryArray -- ( BOOL ) FUNCTION To sort the entries added at object create time. By default the entries added with the LISTV_EntryArray attribute will ocure in the list in the same order as they ocure in the array. When this attribute is set to TRUE these entries will be sorted. Default is FALSE. Applicability is (I). SEE ALSO LISTV_EntryArray NAME LISTV_Select, LISTV_SelectMulti ** V39 ** -- ( ULONG ) FUNCTION To select an entry in the list. The entry you select will also be made visible in the display area. The data required is the logical number of the entry in the list starting with 0 as the first entry. The following magic numbers are allowed in the tag it's data field: LISTV_Select_First -- Select the first entry. ** V38 ** LISTV_Select_Last -- Select the last entry. ** V38 ** LISTV_Select_Next -- Select the next entry. If there is no entry selected yet the first visible entry is selected. ** V38 ** LISTV_Select_Previous -- Select the previous entry. If there is no selected entry yet the first visible entry is selected. ** V38 ** LISTV_Select_Top -- Select the first visible entry. ** V38 ** LISTV_Select_Page_Up -- Select the entry one page above the current. If the currently selected entry is not the top-entry the top entry will be selected. Otherwise the entry one-page up minus one is selected. When no entry is selected the first visible entry is selected. ** V38 ** LISTV_Select_Page_Down -- Select the entry one page below the current. If the currently selected entry is not the bottom-entry the bottom entry will be selected. Otherwise the entry one-page down minus one is selected. When no entry is selected the first visible entry is selected. ** V38 ** LISTV_Select_All -- Selects all entries in the list. Please note that this magic number will only work on listviews in multi- selection mode and it will only work with the LISTV_SelectMulti and LISTV_SelectMultiNotVisible attributes. ** V39 ** LISTV_SelectMulti will select the entry without deselecting any previous selected items while LISTV_Select will deselect any previous selections. Applicability is (SU). SEE ALSO LISTV_SelectNotVisible, LISTV_SelectMultiNotVisible NAME LISTV_MakeVisible -- ( ULONG ) FUNCTION To scroll the list to make the entry appear in the display area of the listview object. The data required is the logical number of the entry in the list starting with 0 as the first entry. Applicability is (SU). NAME LISTV_Entry -- ( APTR ) FUNCTION This tag is sent during notification. The data field is a pointer to the entry which triggered the notification. Applicability is (N). SEE ALSO LISTV_EntryNumber NAME LISTV_EntryNumber -- ( ULONG ) FUNCTION This tag is sent during notification. The data field is the logical number of the entry which triggered the notification. Applicability is (N). SEE ALSO LISTV_Entry NAME LISTV_LastClicked -- ( APTR ) FUNCTION To get a pointer to the last selected entry. This data can be used to detect double-clicking and entry. Example: Object *listview; ULONG ds[2], dm[2], last = 0, clicked; GetAttr( LISTV_LastClicked, listview, &clicked ); if ( clicked == last ) { CurrentTime( &ds[ 1 ], &dm[ 1 ] ); if ( DoubleClick( ds[ 0 ], dm[ 0 ], ds[ 1 ], dm [ 1 ] )) { /* Double clicked */ ... } } CurrentTime( &ds[ 0 ], &dm[ 0 ] ); last = clicked; Applicability is (G). SEE ALSO LISTV_LastClickedNum NAME LISTV_TitleHook -- ( struct Hook * ) FUNCTION To add a hook to render a title for the list. Multi-column listviews normally have a title entry which is rendered in the list area but does not scroll with the list. To support multi-column listviews this hook can be defined which will keep room for a single entry at the top of the list area which is reserved for this purpose. The hook routine is called exactly the same as the LISTV_DisplayHook routine with the exception that the lvr_Entry field of the lvRender structure will contain a NULL pointer. Default is NULL (no title). Applicability is (I). NAME LISTV_ThinFrames -- ( BOOL ) FUNCTION To make all listview object framing appear as thin frames. This will help you to make an aspect-ratio dependant GUI. Default is FALSE. Applicability is (I). NAME PGA_NewLook -- ( BOOL ) FUNCTION To make the scroller of the listview gadget appear in the new look. Default is FALSE. Applicability is (I). NAME LISTV_LastClickedNum -- ( ULONG ) ** V38 ** FUNCTION To return the number of the last selected entry. Applicability is (G). SEE ALSO LISTV_LastClicked NAME LISTV_NumEntries ( ULONG ) ** V38 ** FUNCTION To return the number of entries in the list. Applicability is (G). NAME LISTV_NewPosition -- ( ULONG ) ** V38 ** FUNCTION To notify the object it's targets of the entry it's new position number. When you move an entry with the LVM_MOVE method the object will send out a notification message with this attribute. Applicability is (N). SEE ALSO LVM_MOVE NAME LISTV_MinEntriesShown -- ( UWORD ) FUNCTION To specify how many entries should be visible at all times. Note: The larger this value the bigger the object it's minimum size. Default is 3. Applicability is (I). NAME LISTV_SelectNotVisible, LISTV_SelectMultiNotVisible -- ( ULONG ) ** V39 ** FUNCTION To select an entry in the list. This attribute works exactly like the LISTV_Select and LISTV_SelectMulti attributes with the exception that the selected entry is not moved into the current view area of the list. Applicability is (SU). SEE ALSO LIST_Select, LISTV_SelectMulti NAME LISTV_MultiSelectNoShift -- ( BOOL ) ** V39 ** FUNCTION To allow the user to multi-(de)select the entries in a multi-selection object without having to use the SHIFT key. This tag is only useful when the LISTV_MultiSelect tag is set to TRUE. Default is FALSE. Applicability is (ISU). SEE ALSO LISTV_MultiSelect NAME LISTV_DeSelect -- ( ULONG ) ** V39 ** FUNCTION To deselect a selected entry. The data you pass is the ordinal number of the entry starting at 0 for the first entry in the list. If you supply a value of ~0 (-1) all selected entries in the list are deselected. SEE ALSO LISTV_Select