3 * Allows creation of Filer-like windows which rearrange themselves.
5 * v. 1.00 (13 August 1991)
7 * © 1991-1998 Straylight
10 /*----- Licensing note ----------------------------------------------------*
12 * This file is part of Straylight's Steel library.
14 * Steel is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU General Public License as published by
16 * the Free Software Foundation; either version 2, or (at your option)
19 * Steel is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU General Public License for more details.
24 * You should have received a copy of the GNU General Public License
25 * along with Steel. If not, write to the Free Software Foundation,
26 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
45 * The handle types for the viewer segment
47 typedef struct viewer__viewerstr *viewer;
48 typedef struct viewer__iconstr *viewer_icon;
53 * The whole viewer can have a caller-defined handle, and each icon in it
54 * also has one. The standard event handler gets both. If no ico was
55 * clicked, the icon handle is 0. You should have a handle to your viewer
56 * global data in the icon structure. The raw event handler passes only the
60 typedef void (*viewer_eventhandler)
69 typedef BOOL (*viewer_raweventhandler)
76 typedef void (*viewer_redrawhandler)
88 * Types for data export.
91 typedef BOOL (*viewer_saveproc)(viewer_icon i,char *filename, void *handle);
92 typedef BOOL (*viewer_sendproc)(viewer_icon i,void *handle, int *maxbuf);
93 typedef int (*viewer_printproc)(viewer_icon i,char *filename, void *handle);
99 typedef int (*viewer_compare)(void *a,void *b);
102 * A macro for telling the event handler about a close event. I know it's
103 * not the same, but...
105 #define viewer_CLOSE ((viewer_icon)-1)
108 * A macro for telling the event handler about a help request
110 #define viewer_HELP ((viewer_icon)-2)
113 * A macro representing no icon being clicked.
115 #define viewer_NOICON ((viewer_icon)0)
118 * void viewer_drawFileIcons
130 * Redraw handler which takes into account filetypes of icons. The icons
131 * automatically get new sprites if the sprites for their filetypes change.
132 * For applications, the text is considered to be a filename. Register
133 * this function using viewer_redrawHandler().
136 * viewer_icon icn == the icon to paint
137 * wimp_redrawstr *r == information about this redraw
138 * wimp_box *box == the box to draw the icon in
139 * char *text == the text to display
140 * char *sprite == the sprite to display
141 * BOOL selected == is the icon selected?
142 * void *handle == a caller defined handle (ignored)
145 void viewer_drawFileIcons
157 * viewer viewer_create
169 * Creates a viewer window. Note that viewer windows don't need templates,
170 * and don't contain real wimp icons, just yer normal redrawn-by-
171 * application things (which can be handled by a caller-defined function if
172 * necessary). The banner along the top is optional - if a null pointer is
173 * passed, no banner is included. The sprite area passed applies to all
174 * the icons in the window, although if you want to, you can use your own
175 * redraw routine to handle different sprite areas for them.
178 * int x,int y == the coordinates of the top-left corner of the window
179 * (file windows for editors need good positioning here).
180 * int width == the width of an icon
181 * int height == the height of an icon
182 * sprite_area *spr == the sprite area for the window
183 * char *title == the title of the window
184 * char *banner == the banner heading along the top (like 'Sprite file
185 * window' or something)
188 * A handle to the viewer window. As usual, a NULL pointer indicates
189 * something went wrong.
204 * void viewer_display(viewer v)
207 * Displays a viewer on the screen.
210 * viewer v == the viewer handle
213 void viewer_display(viewer v);
216 * void viewer_hide(viewer v)
219 * Hides an open viewer.
222 * viewer v == the handle
225 void viewer_hide(viewer v);
228 * void viewer_delete(viewer v,void (*freeProc)(void *handle))
231 * Zaps a viewer and everything in it. The function you pass to this
232 * routine is called with every icon handle the viewer has associated with
233 * it, so you don't need to link all the structures together - I've already
237 * viewer v == the viewer to destroy
238 * void (*freeProc)(void *handle) == a function to free one of the caller-
239 * defined viewer icon structures.
242 void viewer_delete(viewer v,void (*freeProc)(void *handle));
245 * void viewer_eventHandler(viewer v,viewer_eventhandler proc,void *handle)
248 * Attaches an event handler to the viewer. The handle passed to this
249 * function is only used for close events, so you can take appropriate
250 * action at the other end. Otherwise, the handle for the icon concerned
251 * is used. Suggested code:
253 * void user_viewer(viewer v,viewer_icon i,wimp_bbits b,void *handle)
255 * user_fileStructure *file=(user_fileStructure *)handle;
256 * user_itemStructure *item=(user_itemStructure *)handle;
259 * case (int)viewer_CLOSE:
260 * ... use 'file' for this bit of code ...
262 * case viewer_NOICON:
263 * ... use 'file' for this bit as well ...
266 * ... use 'item' for this bit of code ...
272 * viewer v == the viewer to attach the handler to
273 * viewer_eventhandler proc == the event handler
274 * void *handle == the handle
277 void viewer_eventHandler(viewer v,viewer_eventhandler proc,void *handle);
280 * void viewer_rawEventHandler
283 * viewer_raweventhandler proc,
288 * Attaches a raw event handler to a viewer. Same as always, this one.
291 * viewer v == the viewer handle
292 * viewer_raweventhandler proc == the handler routine
293 * void *handle == the handle for the user's data
296 void viewer_rawEventHandler
299 viewer_raweventhandler proc,
304 * void viewer_redrawHandler(viewer v,viewer_redrawhandler proc,void *handle)
307 * Adds in a user-defined routine for redrawing icons in the window.
310 * viewer v == the viewer handle
311 * viewer_redrawhandler proc == the routine for doing the redraw
312 * void *handle == a handle to be passed to the routine (a sprite area or
316 void viewer_redrawHandler(viewer v,viewer_redrawhandler proc,void *handle);
319 * void viewer_setIconSize(viewer v,int width,int height)
322 * Sets a new icon size for the viewer. This would normally be
323 * accompanied by a chnge in redraw handler. It would be used e.g. when
324 * using a menu option giving a choice between 'Large icons' and 'Small
328 * viewer v == the viewer which is to receive this change
329 * int width == the new width
330 * int height == the new height
333 void viewer_setIconSize(viewer v,int width,int height);
336 * void viewer_setCompare(viewer v,viewer_compare cmp)
339 * Registers a compare function for the viewer specified. The function
340 * is passed the caller-defined handles of two icons. The function must
341 * return <0 if a<b, >0 if a>b, or ==0 if a==b (like strcmp does). The
342 * viewer's icons are then resorted. Pass 0 to use the default sorting
343 * system (a caseless compare on the icon text)
346 * viewer v == the viewer we're going to set the comparer up for
347 * viewer_compare cmp == the function to do comparing
350 void viewer_setCompare(viewer v,viewer_compare cmp);
353 * viewer_icon viewer_addIcon
363 * Adds a new icon to a viewer window.
366 * viewer v == the handle of the viewer to use.
367 * char *text == the text to put under the icon (may be null)
368 * char *sprite == the sprite to use (may be null)
369 * BOOL inOrder == whether you want the icons sorted into order according
371 * void *handle == the handle you want to pass to the event handler routine
374 * A handle to the icon. If this is NULL, something went majorly wrong
378 viewer_icon viewer_addIcon
388 * void viewer_setFiletype(viewer_icon i,int type)
391 * Sets the filetype of the icon - useful for bins and things. This
392 * filetype overrides the setting given to viewer_exportSelected(). It can
393 * also be used to display the correct icon in the viewer by changing the
394 * redraw handler to viewer_drawFileIcons().
397 * viewer_icon i == the icon to change
398 * int type == the filetype to give it (any valid WIMP filetype will do)
401 void viewer_setFiletype(viewer_icon i,int type);
404 * int viewer_readFiletype(viewer_icon i)
407 * Returns the filetype attached to an icon.
410 * viewer_icon i == the icon handle
413 * The type attached using viewer_setFiletype(), or -1 if none.
416 int viewer_readFiletype(viewer_icon i);
419 * viewer_icon viewer_findIcon(viewer v,char *text)
422 * Searches through a viewer to find an icon with the same text as 'text'.
423 * The search is case-insensitive.
426 * viewer v == the viewer handle
427 * char *text == text to search for
430 * The icon handle, or viewer_NOICON if unsuccessful.
433 viewer_icon viewer_findIcon(viewer v,char *text);
436 * void viewer_removeIcon(viewer_icon i)
439 * Removes the icon specified. This routine is real easy!
442 * viewer_icon i == the icon to remove (they ALL have unique handles, so
446 void viewer_removeIcon(viewer_icon i);
449 * wimp_w viewer_syshandle(viewer v)
452 * Returns the WIMP window handle used for the viewer (and much use may it
456 * viewer v == the viewer handle
459 * The wimp_w window handle
462 wimp_w viewer_syshandle(viewer v);
465 * viewer_icon viewer_iconFromCoords(viewer v,int x,int y)
468 * Given a set of (absolute) coordinates, this returns the icon in the
469 * viewer specified that the point is on. This is mainly useful for menu
470 * maker routines, which will want to be able to select items and so on.
473 * viewer v == the viewer handle
474 * int x == the x-coordinate of the point
475 * int y == the y-coordinate of the point
478 * The icon handle, or viewer__NOICON if there isn't one.
481 viewer_icon viewer_iconFromCoords(viewer v,int x,int y);
484 * void viewer_iconToCoords(viewer_icon i,wimp_box *box)
487 * Calculates the bounding box of the icon given. If there is an error,
488 * nothing is written in the block.
491 * viewer_icon i == the icon we're interested in
492 * wimp_box *box == where to store the coordinates
495 void viewer_iconToCoords(viewer_icon i,wimp_box *box);
498 * BOOL viewer_isSelected(viewer_icon i)
501 * Returns whether an icon is selected or not.
504 * viewer_icon i == the icon handle
507 * TRUE if the icon is selected, or FALSE otherwise.
510 BOOL viewer_isSelected(viewer_icon i);
513 * void viewer_selectIcon(viewer_icon i,BOOL onOrOff)
516 * Selects or deselects the icon specified.
519 * viewer_icon i == the icon handle
520 * BOOL onOrOff == TRUE to select, FALSE to deselect
523 void viewer_selectIcon(viewer_icon i,BOOL onOrOff);
526 * viewer viewer_iconToViewer(viewer_icon i)
529 * Returns the viewer in which an icon is contained.
532 * viewer_icon i == the icon handle
538 viewer viewer_iconToViewer(viewer_icon i);
541 * void *viewer_iconHandle(viewer_icon i)
544 * Returns the handle attached to the icon when it was created
547 * viewer_icon i == the icon in question
550 * The handle attached
553 void *viewer_iconHandle(viewer_icon i);
556 * char *viewer_textOfIcon(viewer_icon i)
559 * Returns the text of the icon given.
562 * viewer_icon i == the icon
565 * Pointer to the string (read only!).
568 char *viewer_textOfIcon(viewer_icon i);
571 * int viewer_selected(viewer v)
574 * Informs caller how many icons are selected.
577 * viewer v == the viewer handle
580 * The number of icons selected.
583 int viewer_selected(viewer v);
586 * int viewer_icons(viewer v)
589 * Returns the number of icons in a viewer.
592 * viewer v == the viewer
595 * The number of icons.
598 int viewer_icons(viewer v);
601 * void viewer_doForIcons
605 * void (*proc)(viewer_icon i,void *handle)
609 * Does the same thing for either all the icons in a viewer, or just the
613 * viewer v == the viewer handle
614 * BOOL onlySelected == whether you want to handle just the selected ones,
616 * void (*proc)(viewer_icon i,void *handle) == the routine to do whatever
617 * it is you want to do.
620 void viewer_doForIcons
624 void (*proc)(viewer_icon i,void *handle)
628 * void viewer_selectAll(viewer v,BOOL onOrOff)
631 * Selects or deselects all the icons in a viewer.
634 * viewer v == the viewer handle
635 * BOOL onOrOff == whether you want the icons to be on or off
638 void viewer_selectAll(viewer v,BOOL onOrOff);
641 * void viewer_clickSelect(viewer v,viewer_icon i,wimp_bbits b)
644 * Handles a click on an icon just like clicks in Filer windows.
647 * viewer v == the viewer handle
648 * viewer_icon i == the icon that was clicked
649 * wimp_bbits b == the mouse button status
652 void viewer_clickSelect(viewer v,viewer_icon i,wimp_bbits b);
655 * char *viewer_menuItem(viewer v,char *header)
658 * Returns a menu item of the form either "~<header> ''",
659 * "<header> '<icon name>'", or "Selection", for inclusion in a menu
663 * viewer v == the viewer handle
664 * char *header == the header for the menu item
667 * A pointer to a read-only string.
670 char *viewer_menuItem(viewer v,char *header);
673 * void viewer_setupMenu(viewer v,char *header,menu m,int i,char *buff)
676 * Writes a menu item out as for the previous routine, but implants it
677 * directly into the menu, so you don't need to fiddle about with things
678 * like that, and also means that the menu pointer changes. The menu item
679 * must have been previously set up with menu_redirectItem. This call will
680 * also set the menu to the correct width. However, ensure that you call
681 * menu_minWidth(m,0) before fiddling with the width!
684 * viewer v == the viewer handle pertaining to this request
685 * menu m == the menu to doctor
686 * int i == the menu item
687 * char *buff == where the menu item wants the data
690 void viewer_setupMenu(viewer v,char *header,menu m,int i,char *buff);
693 * viewer_icon viewer_firstSelected(viewer v)
696 * Returns the handle of the first selected icon.
699 * viewer v == the viewer handle
702 * A handle to the first one, or viewer_NOICON.
705 viewer_icon viewer_firstSelected(viewer v);
708 * void viewer_settitle(viewer v,char *title)
711 * Changes a viewer's title, so that the extent is updated as well.
714 * viewer v == the viewer handle
715 * char *title == the new title string
718 void viewer_settitle(viewer v,char *title);
721 * void viewer_dragSelected(viewer_icon icn,wimp_bbits b)
724 * Drags a set of icons around a window.
727 * viewer_icon icn == the viewer icon handle
728 * wimp_bbits b == the button types that started this lot off
731 void viewer_dragSelected(viewer_icon icn,wimp_bbits b);
734 * void viewer_exportSelected
739 * viewer_saveproc save,
740 * viewer_sendproc send,
741 * viewer_printproc print
745 * Allows you to export the data connected with each selected icon to
746 * another application. The filename used is the icon's text.
749 * viewer_icon icn == the icon on which the user clicked to start the drag
751 * wimp_bbits b == the mouse buttons which started this up.
752 * int filetype == the filetype of the data.
753 * viewer_saveproc save == the save routine (saving and <Wimp$Scrap>
755 * viewer_sendproc send == the send routine (RAM transfer).
756 * viewer_printproc print == the print routine (printing etc.)
759 void viewer_exportSelected
764 viewer_saveproc save,
765 viewer_sendproc send,
766 viewer_printproc print
770 * viewer_icon viewer_helpIcon(viewer v)
773 * Informs the caller which icon the Help system is interested in.
776 * viewer v == the viewer handle
779 * The icon's handle (or maybe viewer_NOICON)
782 viewer_icon viewer_helpIcon(viewer v);