Config Library: 4.14 Object Class Reference: PrefTocListClass

PrefTocListClass allows users to choose a device driver by selecting the appropriate device name. It is assumed that each driver can control one or more types of devices. When you set up each driver, you will set up strings to describe which devices that driver can control.

This class is a fully functional subclass of PrefDynamicListClass (i.e. it handles those messages one must intercept to create a viable Preferences dynamic list class). It can be used to scan a list of files (not necessarily device drivers), as long as all of those files are in the same directory and have the same characters in their token.

Code Display 22-13 PrefTocListClass Instance Data

@class PrefTocListClass, PrefDynamicListClass;

@instance TocUpdateCategoryFlags  PTLI_flags = 0;

typedef WordFlags  TocUpdateCategoryFlags;
#define  TUCF_EXTENDED_DEVICE_DRIVERS 0x8000
/* Files being enumerated are assumed to be extended device drivers. */

#define TUCF_CUSTOM_FILES 0x4000
/* The TUCP_fileArrayElementSize field will be used when creating the files array.
 * Otherwise, each element of the files array will be of size TocFileStruct. 
 * NOTE: If this flag is used, the data structure used for each file
 * element MUST contain TocFileStruct as its first element. */

#define TUCF_ADD_CALLBACK 0x2000
/* TUCP_addCallback contains a fptr to a callback
 * routine that will be called when a file is added to the files array. */

#define TUCF_DIRECTORY_NOT_FOUND 0x1000
/* Don't actually scan the directory, because it doesn't exist.
 * Just create the category, and leave it empty. */

@instance TocCategoryStruct PTLI_tocInfo = {"", 0, 0};

typedef struct {
	TokenChars 		 TCS_tokenChars;
	DBGroupAndItem 		TCS_files; 		/* file name array */
	DBGroupAndItem 		TCS_devices; 		/* device name array--only if
					 * TCF_EXTENDED_DEVICE_DRIVERS is set. */
}  TocCategoryStruct;

@vardata PrefTocExtraEntry  ATTR_PREF_TOC_LIST_EXTRA_ENTRY_1; 
@vardata PrefTocExtraEntry ATTR_PREF_TOC_LIST_EXTRA_ENTRY_2;

typedef struct {
	ChunkHandle 		 PTEE_item;
	/* lptr of item name. For device lists, this is 
	 * the device. For others, this is the file name */

	ChunkHandle 		PTEE_driver;
	/* Driver name (for device lists ONLY) */

	word 		PTEE_info;
	/* Extra word of information */
}  PrefTocExtraEntry;

@vardata char ATTR_PREF_TOC_LIST_INFO_KEY[];
/* This key is used to write the "info" word for device lists */

Use ATTR_GEN_PATH_DATA to tell the PrefTocList object in which directory to look for the device drivers. The PrefTocList will store the list of device drivers and device names in DB items referenced in the PTLI_tocInfo field's TCS_files and TCS_devices slots--it will do this automatically, so if you wish the default behavior, leave these as zero when declaring the object. If you will write your own handlers for keeping track of driver information, you may wish to work with these fields as there are some routines which have been set up to work with them.

Code Display 22-14 PrefTocList Framework

@object PrefTocListClass MyPrefToc = {
	PTLI_flags		= @default | TUCF_EXTENDED_DEVICE_DRIVERS;
	PTLI_tocInfo		= {"TOKN", 0, 0};
	HINT_ITEM_GROUP_SCROLLABLE;
	ATTR_GEN_INIT_FILE_KEY = "keyName";
	ATTR_GEN_PATH_DATA = { file path containing drivers };
}

The following routines are rather esoteric. You should only use them if you wish to subclass PrefTocListClass ' behavior and wish to continue using its existing data structures.

TocSortedNameArrayAdd(): Use this routine to add a new name to a sorted array. The new name will be inserted in its correct place in the alphabetically sorted array.
TocSortedNameArrayFind(): This routine determines whether a given name is in the TOC List's sorted name array, and will return the position of the name's element if found.
TocFindCategory(): Use this routine to find a category in the Toc file. The TCS_tokenChars field of the passed TocCategoryStruct should already be filled in; this routine will fill in the other fields.
TocNameArrayFind(): Use this routine to get back the token associated with a name in the name array. If the name is not found, the routine will return CA_NULL_ELEMENT.
TocNameArrayGetElement(): This routine takes a name array and a token and returns information about the name array element with the given token.
TocUpdateCategory(): This complicated routine will update a category using a callback routine which you must write. It updates the file lists by scanning the current directory.
TocNameArrayAdd(): Use this routine to add an element to a Toc name array.
TocDBLock(): Use this routine to lock one of the name arrays.
TocDBLockGetRef(): This C-only routine does the same thing as TocDBLock() and also returns the DB item's pointer and optr.
TocGetFileHandle(): Use this routine to get the handle of the file in which all Toc device driver information is stored.

MSG_PREF_TOC_LIST_GET_SELECTED_ITEM_INFO

Boolean MSG_PREF_TOC_LIST_GET_SELECTED_ITEM_INFO(
        word 		*infoPtr);

This message returns the information word about the currently selected item. This message can only be used with PrefTocList objects that have the TCF_EXTENDED_DEVICE_DRIVERS flag set.

Parameters: infoPtr Pointer to a word in which to return the info word.

Return: Returns false (i.e. zero) if item was found, returns true (i.e. non-zero) if item was not found.

MSG_PREF_TOC_LIST_GET_SELECTED_DRIVER_NAME

word MSG_PREF_TOC_LIST_GET_SELECTED_DRIVER_NAME(
        char 		*buf,
        word 		bufSize);

This message returns the name of the driver for the selected device. This message may only be used if TCF_EXTENDED_DEVICE_DRIVERS is set.

Parameters: buf Pointer to buffer to fill with the driver name.

bufSize: The size of buf.

Return: If the device name fits in buf, then buf is filled and the message returns the size of the device name. If the device name doesn't fit, then the message will return zero.

MSG_PREF_TOC_LIST_GET_SELECTED_ITEM_PATH

void MSG_PREF_TOC_LIST_GET_SELECTED_ITEM_PATH(
        TocItemPath 		*data);

This message returns the absolute path of the selected driver or file.

Structures:

typedef struct {
  word 			 TIP_disk; /* disk handle */

  MemHandle 			TIP_pathBlock; 
	/* Handle of block holding path (locked) */

  char 			*TIP_path; 
	/* Locked null-terminated absolute path */

}  TocItemPath;

MSG_PREF_TOC_LIST_CHECK_DEVICE_AVAILABLE

Boolean MSG_PREF_TOC_LIST_CHECK_DEVICE_AVAILABLE(
        word 		*retvalPtr);

This message determines if the device selected by the list is available in the machine. This message may only be called for PrefTocList objects that have the TCF_EXTENDED_DEVICE_DRIVERS flag set.

Parameters: retValPtr Pointer to a word which will be filled with the return value.

Return: Returns true (i.e. non-zero if the device is available; if the driver is a video driver, *retValPtr is set to the device's DisplayType . If the device is not available, returns false (i.e. zero); retValPtr is zero of the device doesn't exist; otherwise it will be the value of the appropriate GeodeLoadError plus one.

GEOS SDK TechDocs |

4.13 PrefTriggerClass