home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Club Amiga de Montreal - CAM
/
CAM_CD_1.iso
/
files
/
418.lha
/
ListWindowPackage
/
listwin_pak.doc
< prev
next >
Wrap
Text File
|
1990-09-10
|
21KB
|
767 lines
TABLE OF CONTENTS
listwin_pak/AddListWindowName
listwin_pak/AddName
listwin_pak/AllocateNameList
listwin_pak/AllocateNameListPtrs
listwin_pak/CloseListWindow
listwin_pak/CloseListWindowPackage
listwin_pak/FreeListWindow
listwin_pak/FreeNameList
listwin_pak/FreeNameListPtrs
listwin_pak/HandleListWindow
listwin_pak/InitListWindow
listwin_pak/InitListWindowPackage
listwin_pak/OpenListWindow
listwin_pak/MakeListWindow
listwin_pak/ResizeNameList
listwin_pak/RemoveName
listwin_pak/RemoveListWindowName
listwin_pak/SelectListWindowName
listwin_pak/SetListWindowNameList
listwin_pak/SetNameList
listwin_pak/SetNameListPos
listwin_pak/SortListWindowNames
listwin_pak/SortNameList
listwin_pak/AddListWindowName listwin_pak/AddListWindowName
NAME
AddListWindowName - add a new name to a List Window name-list
SYNOPSIS
AddListWindowName(window, name);
PROTOTYPE
void AddListWindowName(struct Window *, UBYTE *);
FUNCTION
AddListWindowName calls AddName on the specified ListWindow's NameList
structure to add the new name to the window's name list, then redraws
the list.
INPUTS
window -- pointer to the open List Window
name -- UBYTE pointer to the name to add
RETURNS
None.
BUGS
None.
SEE ALSO
AddName(), RemoveListWindowName()
listwin_pak/AddName listwin_pak/AddName
NAME
AddName - add a new name to a NameList
SYNOPSIS
AddName(namelist, name);
PROTOTYPE
void AddName(struct NameList *, UBYTE *);
FUNCTION
AddName adds the new pointer to the specified name to the specified
NameList's name pointer array. If the name array is full, AddName()
calls ResizeNameList() to add five more available pointer spaces in
the array, then adds the new name pointer. After the new name is added,
the NameList is automatically sorted with a call to SortNameList().
INPUTS
namelist -- pointer to the prepared NameList structure
name -- UBYTE pointer to the name to add
RETURNS
None.
BUGS
None.
SEE ALSO
RemoveName(), AddListWindowName()
listwin_pak/AllocateNameList listwin_pak/AllocateNameList
NAME
AllocateNameList - allocate a NameList structure and name array
SYNOPSIS
namelist = AllocateNameList(names);
PROTOTYPE
struct NameList *AllocateNameList(SHORT);
FUNCTION
AllocateNameList allocates a new NameList structure, and then calls
AllocateNameListPtrs to allocate the name pointer array for the number
of names specified.
INPUTS
names -- number of pointers in the array to allocate
RETURNS
Pointer to the allocated and initialized NameList structure if
successful, NULL otherwise.
BUGS
None.
SEE ALSO
AllocateNameListPtrs(), FreeNameList()
listwin_pak/AllocateNameListPtrs listwin_pak/AllocateNameListPtrs
NAME
AllocateNameListPtrs - allocates a name pointer array for the NameList
SYNOPSIS
success = AllocateNameListPtrs(namelist, names);
PROTOTYPE
int AllocateNameListPtrs(struct NameList *, SHORT);
FUNCTION
AllocateNameListPtrs allocates a UBYTE array of pointers, to be later
filled with the addresses of text strings use in the NameList. It
then attaches this array to the specified NameList.
INPUTS
namelist -- pointer to an allocated NameList structure
names -- number of UBYTE pointers to be allocated in the array
RETURNS
TRUE if successfull, NULL otherwise.
BUGS
None.
SEE ALSO
FreeNameListPtrs()
listwin_pak/CloseListWindow listwin_pak/CloseListWindow
NAME
CloseListWindow - close and free a ListWindow
SYNOPSIS
CloseListWindow(window);
PROTOTYPE
void CloseListWindow(struct Window *);
FUNCTION
CloseListWindow frees up the memory allocated by MakeListWindow(), by
calling FreeListWindow(), and then closes the Window. Use this in
conjunction with OpenListWindow() if no special processing is being
done to the Window other than the List information.
INPUTS
window -- pointer to the open List Window to free and close
RETURNS
None.
BUGS
None.
SEE ALSO
OpenListWindow(), FreeListWindow()
listwin_pak/CloseListWindowPackage listwin_pak/CloseListWindowPackage
NAME
CloseListWindowPackage - frees resources allocated with
InitListWindowPackage()
SYNOPSIS
CloseListWindowPackage();
PROTOTYPE
void CloseListWindowPackage(void);
FUNCTION
CloseListWindowPackage closes the ConsoleDevice opened with a call to
InitListWindowPackage(). This is not necessary if key-positioning of
the list. It is not necessary to call this function if
InitListWindowPackage() was not called.
INPUTS
None.
RETURNS
None.
BUGS
None.
SEE ALSO
InitListWindowPackage()
listwin_pak/FreeListWindow listwin_pak/FreeListWindow
NAME
FreeListWindow - free the memory allocated with MakeListWindow()
SYNOPSIS
FreeListWindow(window);
PROTOTYPE
void FreeListWindow(struct Window *);
FUNCTION
FreeListWindow frees up the memory allocated with MakeListWindow(),
including the removal of the scroll gadgets and freeing of the NameList
if a pointer to it still remains. If your application sets up and
maintains its own NameList structures, be sure to call
SetListWindowNameList() with a NULL pointer for the NameList, before
calling this function, so FreeListWindow() will not attempt to
deallocate that memory. If you use InitListWindow() to set up the
NameList, then it is safe to simply call this function to clear up
all allocated memory for that List Window.
Use this function in conjunction with MakeListWindow() if you are
doing something special to the windows in addition to the list.
This function does not close the window.
INPUTS
window -- pointer to the Window that contains the List Window to free
RETURNS
None.
BUGS
None.
SEE ALSO
MakeListWindow()
listwin_pak/FreeNameList listwin_pak/FreeNameList
NAME
FreeNameList - free a NameList and its name pointer array
SYNOPSIS
FreeNameList(namelist);
PROTOTYPE
void FreeNameList(struct NameList *);
FUNCTION
FreeNameList calls FreeNameListPtrs() to deallocate the specified
NameList's pointer array, then frees the NameList structure.
INPUTS
namelist -- pointer to the NameList to deallocate
RETURNS
None.
BUGS
None.
SEE ALSO
AllocateNameList(), FreeNameListPtrs()
listwin_pak/FreeNameListPtrs listwin_pak/FreeNameListPtrs
NAME
FreeNameListPtrs - free a NameList's name pointer array
SYNOPSIS
FreeNameListPtrs(namelist);
PROTOTYPE
void FreeNameListPtrs(struct NameList *);
FUNCTION
FreeNameListPtrs frees the name pointer array of the specified NameList
structure.
INPUTS
namelist -- pointer to the NameList to free the name array of
RETURNS
None.
BUGS
None.
SEE ALSO
AllocateNameListPtrs(), FreeNameList()
listwin_pak/HandleListWindow listwin_pak/HandleListWindow
NAME
HandleListWindow - handle user operations on a List Window
SYNOPSIS
code = HandleListWindow(message, buffer);
PROTOTYPE
int HandleListWindow(struct IntuiMessage *, UBYTE *);
FUNCTION
HandleListWindow controls resizing/drawing of the ListWindow, and
handles various messages directed toward the window, such as scrolling
gadgets, arrow-keys, and name selection. Once your application program
realizes the message is directed toward a List Window, pass an entire
copy of the message to this function, along with a pointer to a text
buffer to hold the name if selected. Be sure to make your copy of the
message before ReplyMsg/ing to it.
INPUTS
message -- pointer to a copy of the IntuiMessage structure received
from the host application
buffer -- pointer to a UBYTE buffer large enough to hold the name
of the largest string in the list
RETURNS
CLOSE_LISTWINDOW -- if the window has a CLOSEWINDOW gadget, and this
was selected, this integer code is returned
GOT_NAME -- if a name was selected, or the list was scrolled
with a selected "slot", this code is returned. Look
in the buffer to find the name that was under the
selected "slot".
LISTWINDOW_NONE -- nothing your program needs to know about happened
to the window (well, you MIGHT need to know, but
this package is meant to be transparent). You get
this if CLOSEWINDOW WASN'T selected or there are
no selected names (this includes scrolling,
dragging, and resizing).
BUGS
None.
SEE ALSO
listwin_pak/InitListWindow listwin_pak/InitListWindow
NAME
InitListWindow - set up a List Window's name list
SYNOPSIS
success = InitListWindow(window, name_array, names, position);
PROTOTYPE
int InitListWindow(struct Window *, UBYTE **, SHORT, SHORT);
FUNCTION
InitListWindow creates a NameList and copies the specified name-list
array into it, then draws the window starting the list at the specified
position. This is used if you are passing a pre-created array of text
string pointers, with the specified number of pointers in the array.
INPUTS
window -- pointer to the window containing the ListWindow to initialize
name_array -- pointer to an array of UBYTE pointers to text strings
names -- number of text string pointers in the array
position -- position to draw the list at (0 = top of list)
RETURNS
TRUE if the ListWindow exists and the NameList was allocated
successfully, NULL of otherwise.
BUGS
None.
SEE ALSO
SetListWindowNameList()
listwin_pak/InitListWindowPackage listwin_pak/InitListWindowPackage
NAME
InitListWindowPackage - initialize ListWindow Package module-locals
SYNOPSIS
success = InitListWindowPackage();
PROTOTYPE
int InitListWindowPackage(void);
FUNCTION
InitListWindowPackage opens the Console Device and initializes proper
translation of RAWKEY codes into the default KEYMAP character codes.
InitListWindowPackage is necessary only if you require key searching
of your lists. This is accomplished by holding SHIFT and a key when
the desired list window is active. The list window will display the
first name in the list that has the key pressed as its first letter,
or the next closest name if none has that letter. Normal ARROW-KEY
scrolling of the list will work without a call to this function.
INPUTS
None.
RETURNS
TRUE if the ConsoleDevice is successfully opened, NULL otherwise.
BUGS
None.
SEE ALSO
CloseListWindowPackage()
listwin_pak/OpenListWindow listwin_pak/OpenListWindow
NAME
OpenListWindow - open a window and initialize it as a List Window
SYNOPSIS
window = OpenListWindow(new_window);
PROTOTYPE
struct Window *OpenListWindow(struct NewWindow *);
FUNCTION
OpenListWindow opens a standard window and calls MakeListWindow() to
initialize it as a List Window.
INPUTS
new_window -- pointer to a NewWindow structure (see Intuition Manual)
The List Window will behave depending on what flags you have set within
the NewWindow structure (CLOSEWINDOW, WINDOWDRAG, WINDOWSIZING, etc.).
RETURNS
If successful, returns a pointer to the newly opened Window, otherwise
NULL.
BUGS
None.
SEE ALSO
CloseListWindow(), MakeListWindow()
InitListWindow(), HandleListWindow()
listwin_pak/MakeListWindow listwin_pak/MakeListWindow
NAME
MakeListWindow - makes the specified window into a List Window
SYNOPSIS
success = MakeListWindow(window);
PROTOTYPE
int MakeListWindow(struct Window *);
FUNCTION
MakeListWindow takes the specified window and allocates the necessary
List Window structures to make it into a List Window, including the
scroller gadgets and internal state information for that window. It
attaches this information to the UserData pointer of the Window
structure, so be sure not to use this pointer for other application
use, as other ListWindow functions use this data space.
INPUTS
window -- pointer to an opened Window to be made into a List Window
RETURNS
TRUE if all memory is allocated successfully, NULL if not.
BUGS
None.
SEE ALSO
FreeListWindow(), InitListWindow()
listwin_pak/ResizeNameList listwin_pak/ResizeNameList
NAME
ResizeNameList - change the size of a NameList name pointer array
SYNOPSIS
success = ResizeNameList(namelist, names);
PROTOTYPE
int ResizeNameList(struct NameList *, ULONG);
FUNCTION
ResizeNameList changes the size of a NameList name pointer array.
A new pointer array is allocated, and the pointers from the original
are copied (up until the length of the new array, if it is smaller)
into the new array. If the sizes are the same, nothing happens.
INPUTS
namelist -- pointer to the NameList structure to affect
names -- number of names in the new list
RETURNS
TRUE if the new array is successfully allocated, NULL otherwise.
BUGS
None.
SEE ALSO
AddName(), RemoveName()
listwin_pak/RemoveName listwin_pak/RemoveName
NAME
RemoveName - removes a name from a NameList
SYNOPSIS
RemoveName(namelist, name);
PROTOTYPE
void RemoveName(struct NameList *, UBYTE *);
FUNCTION
RemoveName searches the specified NameList name pointer array for the
specified name, and, if found, removes the name pointer from the list.
After the name is removed, the list is resorted with a call to
SortNameList().
INPUTS
namelist -- pointer to the NameList structure to affect
name -- UBYTE pointer to the name to remove
RETURNS
None.
BUGS
None.
SEE ALSO
RemoveListWindowName(), AddName()
listwin_pak/RemoveListWindowName listwin_pak/RemoveListWindowName
NAME
RemoveListWindowName - remove a name from a List Window list
SYNOPSIS
RemoveListWindowName(window, name);
PROTOTYPE
void RemoveListWindowName(struct Window *, UBYTE *);
FUNCTION
RemoveListWindowName calls RemoveName on the specified ListWindow's
NameList structure to remove the specified name from the list. Then
it redraws the list.
INPUTS
window -- pointer to the List Window to affect
name -- UBYTE pointer to the name to remove from the list
RETURNS
None.
BUGS
None.
SEE ALSO
RemoveName(), AddListWindowName()
listwin_pak/SelectListWindowName listwin_pak/SelectListWindowName
NAME
SelectListWindowName - select and highlight a List Window name
SYNOPSIS
SelectListWindowName(window, name);
PROTOTYPE
void SelectListWindowName(struct Window *, UBYTE *);
FUNCTION
SelectListWindowName searches the specified List Window for the
specified name, and, if found, redraws the list with a view of the
name and then selects and hilights it.
INPUTS
window -- pointer to the List Window to affect
name -- UBYTE pointer to the name to select
RETURNS
None.
BUGS
None.
SEE ALSO
listwin_pak/SetListWindowNameList listwin_pak/SetListWindowNameList
NAME
SetListWindowNameList - assign a NameList to a ListWindow
SYNOPSIS
SetListWindowNameList(window, namelist, position);
PROTOTYPE
void SetListWindowNameList(struct Window *, struct NameList *, SHORT);
FUNCTION
SetListWindowNameList assigns the specified NameList to the specified
ListWindow, and then redraws the list starting at the specified
position. This is useful if you maintain your own NameLists within your
application, and simply need to assign the proper ones to your List
Window. If your application has allocated its own NameLists, be sure
to pass a NULL pointer for the namelist to this function, before
calling CloseListWindow() or FreeListWindow(), unless you want the
package to deallocate your NameList for you.
This function calls SetNameListPos() to redraw the list.
INPUTS
window -- pointer to the open Window to set the new NameList for
namelist -- pointer to the NameList to assign to the List Window
position -- position to draw the list at (0 == start of list)
RETURNS
None.
BUGS
None.
SEE ALSO
SetNameListPos()
listwin_pak/SetNameList listwin_pak/SetNameList
NAME
SetNameList - copy a prepared array of UBYTE pointers into a NameList
SYNOPSIS
SetNameList(namelist, name_array, names);
PROTOTYPE
void SetNameList(struct NameList *, UBYTE **, ULONG);
FUNCTION
SetNameList copies the pointers provided in a UBYTE pointer array
into the array of a prepared NameList structure, up to the specified
number of names, or the available number of name pointers within the
NameList, whichever is least. Make sure the NameList has an allocated
pointer array before using this function. SetNameList does not adjust
the size of the destination NameList to fit the number of name pointers
provided.
INPUTS
namelist -- pointer to the prepared NameList structure to copy the
name pointers into
name_array -- a pointer to an array of UBYTE text pointers which point
to NULL-terminated strings
names -- number of name pointers in array
RETURNS
None.
BUGS
None.
SEE ALSO
ResizeNameList(), AddName(), RemoveName()
listwin_pak/SetNameListPos listwin_pak/SetNameListPos
NAME
SetNameListPos - redraw the list at the specified position
SYNOPSIS
SetNameListPos(window, position);
PROTOTYPE
void SetNameListPos(struct Window *, SHORT);
FUNCTION
SetNameListPos redraws the specified ListWindow starting at the
specified position (0 == start of list). Use a very high number to
set it at the last page if information, is this is necessary. If there
is no NameList for the specified List Window, this will clear the
entries from the window.
INPUTS
window -- pointer to the opened Window to redraw the NameList for
position -- position to start the list at
RETURNS
None.
BUGS
None.
SEE ALSO
SetListWindowNameList()
listwin_pak/SortListWindowNames listwin_pak/SortListWindowNames
NAME
SortListWindowNames - sort the list in a ListWindow
SYNOPSIS
SortListWindowNames(window);
PROTOTYPE
void SortListWindowNames(struct Window *);
FUNCTION
SortListWindowNames calls SortNameList() on the NameList structure
within the ListWindow data.
INPUTS
window -- pointer to the open List Window
RETURNS
None.
BUGS
None (see SortNameList()).
SEE ALSO
SortNameList()
listwin_pak/SortNameList listwin_pak/SortNameList
NAME
SortNameList - sort the names within a prepared NameList structure
SYNOPSIS
SortNameList(namelist);
PROTOTYPE
void SortNameList(struct NameList *);
FUNCTION
SortNameList calls the internal Lattice sorting algorithm tqsort()
on the array of text pointers within the specified NameList structure,
to arrange the pointers so that their associated strings are in
alphabetic order.
INPUTS
namelist -- pointer to the prepared NameList structure to sort
RETURNS
None.
BUGS
None (unless your standard library doesn't have tqsort()).
SEE ALSO
SortListWindowNames()