Initial revision

[ssr] / StraySrc / Libraries / Steel / h / viewer

/*
 * viewer
 *  Allows creation of Filer-like windows which rearrange themselves.
 *
 * v. 1.00 (13 August 1991)
 *
 * © 1991-1998 Straylight
 */

/*----- Licensing note ----------------------------------------------------*
 *
 * This file is part of Straylight's Steel library.
 *
 * Steel is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * Steel is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Steel.  If not, write to the Free Software Foundation,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef __viewer_h
#define __viewer_h

#ifndef __wimp_h
#include "wimp.h"
#endif

#ifndef __sprite_h
#include "sprite.h"
#endif

#ifndef __menu_h
#include "menu.h"
#endif

/*
 * The handle types for the viewer segment
 */
typedef struct viewer__viewerstr *viewer;
typedef struct viewer__iconstr *viewer_icon;

/*
 * Event handler types
 *
 * The whole viewer can have a caller-defined handle, and each icon in it
 * also has one.  The standard event handler gets both.  If no ico was 
 * clicked, the icon handle is 0.  You should have a handle to your viewer 
 * global data in the icon structure.  The raw event handler passes only the
 * global handle.
 */

typedef void (*viewer_eventhandler)
(
  viewer v,
  viewer_icon i,
  wimp_bbits b,
  void *vhandle,
  void *ihandle
);

typedef BOOL (*viewer_raweventhandler)
(
  viewer v,
  wimp_eventstr *e,
  void *handle
);

typedef void (*viewer_redrawhandler)
(
  viewer_icon i,
  wimp_redrawstr *r,
  wimp_box *box,
  char *text,
  char *sprite,
  BOOL selected,
  void *handle
);

/*
 * Types for data export.
 */

typedef BOOL (*viewer_saveproc)(viewer_icon i,char *filename, void *handle);
typedef BOOL (*viewer_sendproc)(viewer_icon i,void *handle, int *maxbuf);
typedef int (*viewer_printproc)(viewer_icon i,char *filename, void *handle);

/*
 * For sorting icons
 */

typedef int (*viewer_compare)(void *a,void *b);

/*
 * A macro for telling the event handler about a close event.  I know it's 
 * not the same, but...
 */
#define viewer_CLOSE ((viewer_icon)-1)

/*
 * A macro for telling the event handler about a help request
 */
#define viewer_HELP ((viewer_icon)-2)

/*
 * A macro representing no icon being clicked.
 */
#define viewer_NOICON ((viewer_icon)0)

/*
 * void viewer_drawFileIcons
 * (
 *   viewer_icon icn,
 *   wimp_redrawstr *r,
 *   wimp_box *box,
 *   char *text,
 *   char *sprite,
 *   BOOL selected,
 *   void *handle
 * )
 *
 * Use
 *  Redraw handler which takes into account filetypes of icons.  The icons
 *  automatically get new sprites if the sprites for their filetypes change.
 *  For applications, the text is considered to be a filename.  Register
 *  this function using viewer_redrawHandler().
 *
 * Parameters
 *  viewer_icon icn == the icon to paint
 *  wimp_redrawstr *r == information about this redraw
 *  wimp_box *box == the box to draw the icon in
 *  char *text == the text to display
 *  char *sprite == the sprite to display
 *  BOOL selected == is the icon selected?
 *  void *handle == a caller defined handle (ignored)
 */

void viewer_drawFileIcons
(
  viewer_icon icn,
  wimp_redrawstr *r,
  wimp_box *box,
  char *text,
  char *sprite,
  BOOL selected,
  void *handle
);

/*
 * viewer viewer_create
 * (
 *   int x,
 *   int y,
 *   int width,
 *   int height,
 *   sprite_area *spr,
 *   char *title,
 *   char *banner
 * )
 *
 * Use
 *  Creates a viewer window.  Note that viewer windows don't need templates,
 *  and don't contain real wimp icons, just yer normal redrawn-by-
 *  application things (which can be handled by a caller-defined function if
 *  necessary).  The banner along the top is optional - if a null pointer is
 *  passed, no banner is included.  The sprite area passed applies to all
 *  the icons in the window, although if  you want to, you can use your own
 *  redraw routine to handle different sprite areas for them.
 *
 * Parameters
 *  int x,int y == the coordinates of the top-left corner of the window
 *    (file windows for editors need good positioning here).
 *  int width == the width of an icon
 *  int height == the height of an icon
 *  sprite_area *spr == the sprite area for the window
 *  char *title == the title of the window
 *  char *banner == the banner heading along the top (like 'Sprite file
 *    window' or something)
 *
 * Returns
 *  A handle to the viewer window.  As usual, a NULL pointer indicates
 *   something went wrong.
 */

viewer viewer_create
(
  int x,
  int y,
  int width,
  int height,
  sprite_area *spr,
  char *title,
  char *banner
);

/*
 * void viewer_display(viewer v)
 *
 * Use
 *  Displays a viewer on the screen.
 *
 * Parameters
 *  viewer v == the viewer handle
 */

void viewer_display(viewer v);

/*
 * void viewer_hide(viewer v)
 *
 * Use
 *  Hides an open viewer.
 *
 * Parameters
 *  viewer v == the handle
 */

void viewer_hide(viewer v);

/*
 * void viewer_delete(viewer v,void (*freeProc)(void *handle))
 *
 * Use
 *  Zaps a viewer and everything in it.  The function you pass to this
 *  routine is called with every icon handle the viewer has associated with
 *  it, so you don't need to link all the structures together - I've already
 *  done that here!
 *
 * Parameters
 *  viewer v == the viewer to destroy
 *  void (*freeProc)(void *handle) == a function to free one of the caller-
 *    defined viewer icon structures.
 */

void viewer_delete(viewer v,void (*freeProc)(void *handle));

/*
 * void viewer_eventHandler(viewer v,viewer_eventhandler proc,void *handle)
 *
 * Use
 *  Attaches an event handler to the viewer.  The handle passed to this
 *  function is only used for close events, so you can take appropriate
 *  action at the other end.  Otherwise, the handle for the icon concerned
 *  is used.  Suggested code:
 *
 * void user_viewer(viewer v,viewer_icon i,wimp_bbits b,void *handle)
 * {
 *   user_fileStructure *file=(user_fileStructure *)handle;
 *   user_itemStructure *item=(user_itemStructure *)handle;
 *   switch ((int)i)
 *   {
 *     case (int)viewer_CLOSE:
 *       ... use 'file' for this bit of code ...
 *       break;
 *     case viewer_NOICON:
 *       ... use 'file' for this bit as well ...
 *       break;
 *     default:
 *       ... use 'item' for this bit of code ...
 *       break;
 *   }  
 * }
 *
 * Parameters
 *  viewer v == the viewer to attach the handler to
 *  viewer_eventhandler proc == the event handler
 *  void *handle == the handle
 */

void viewer_eventHandler(viewer v,viewer_eventhandler proc,void *handle);

/*
 * void viewer_rawEventHandler
 * (
 *   viewer v,
 *   viewer_raweventhandler proc,
 *   void *handle
 * )
 *
 * Use
 *  Attaches a raw event handler to a viewer.  Same as always, this one.
 *
 * Parameters
 *  viewer v == the viewer handle
 *  viewer_raweventhandler proc == the handler routine
 *  void *handle == the handle for the user's data
 */

void viewer_rawEventHandler
(
  viewer v,
  viewer_raweventhandler proc,
  void *handle
);

/*
 * void viewer_redrawHandler(viewer v,viewer_redrawhandler proc,void *handle)
 *
 * Use
 *  Adds in a user-defined routine for redrawing icons in the window.
 *
 * Parameters
 *  viewer v == the viewer handle
 *  viewer_redrawhandler proc == the routine for doing the redraw
 *  void *handle == a handle to be passed to the routine (a sprite area or
 *    something)
 */

void viewer_redrawHandler(viewer v,viewer_redrawhandler proc,void *handle);

/*
 * void viewer_setIconSize(viewer v,int width,int height)
 *
 * Use
 *  Sets a new icon size for the viewer.  This would normally be
 *  accompanied by a chnge in redraw handler.  It would be used e.g. when
 *  using a menu option giving a choice between 'Large icons' and 'Small
 *  icons'.
 *
 * Parameters
 *  viewer v == the viewer which is to receive this change
 *  int width == the new width
 *  int height == the new height
 */
 
void viewer_setIconSize(viewer v,int width,int height);

/*
 * void viewer_setCompare(viewer v,viewer_compare cmp)
 *
 * Use
 *  Registers a compare function for the viewer specified.  The function
 *  is passed the caller-defined handles of two icons.  The function must
 *  return <0 if a<b, >0 if a>b, or ==0 if a==b (like strcmp does).  The
 *  viewer's icons are then resorted.  Pass 0 to use the default sorting
 *  system (a caseless compare on the icon text)
 *
 * Parameters
 *  viewer v == the viewer we're going to set the comparer up for
 *  viewer_compare cmp == the function to do comparing
 */

void viewer_setCompare(viewer v,viewer_compare cmp);

/*
 * viewer_icon viewer_addIcon
 * (
 *   viewer v,
 *   char *text,
 *   char *sprite,
 *   BOOL inOrder,
 *   void *handle
 * )
 *
 * Use
 *  Adds a new icon to a viewer window.  
 *
 * Parameters
 *  viewer v == the handle of the viewer to use.
 *  char *text == the text to put under the icon (may be null)
 *  char *sprite == the sprite to use (may be null)
 *  BOOL inOrder == whether you want the icons sorted into order according
 *   to the text fields
 *  void *handle == the handle you want to pass to the event handler routine
 *
 * Returns
 *  A handle to the icon.  If this is NULL, something went majorly wrong 
 *  (sorry, John)
 */

viewer_icon viewer_addIcon
(
  viewer v,
  char *text,
  char *sprite,
  BOOL inOrder,
  void *handle
);

/*
 * void viewer_setFiletype(viewer_icon i,int type)
 *
 * Use
 *  Sets the filetype of the icon - useful for bins and things.  This
 *  filetype overrides the setting given to viewer_exportSelected().  It can
 *  also be used to display the correct icon in the viewer by changing the
 *  redraw handler to viewer_drawFileIcons().
 *
 * Parameters
 *  viewer_icon i == the icon to change
 *  int type == the filetype to give it (any valid WIMP filetype will do)
 */

void viewer_setFiletype(viewer_icon i,int type);

/*
 * int viewer_readFiletype(viewer_icon i)
 *
 * Use
 *  Returns the filetype attached to an icon.
 *
 * Parameters
 *  viewer_icon i == the icon handle
 *
 * Returns
 *  The type attached using viewer_setFiletype(), or -1 if none.
 */

int viewer_readFiletype(viewer_icon i);

/*
 * viewer_icon viewer_findIcon(viewer v,char *text)
 *
 * Use
 *  Searches through a viewer to find an icon with the same text as 'text'.
 *  The search is case-insensitive.
 *
 * Parameters
 *  viewer v == the viewer handle
 *  char *text == text to search for
 *
 * Returns
 *  The icon handle, or viewer_NOICON if unsuccessful.
 */

viewer_icon viewer_findIcon(viewer v,char *text);

/*
 * void viewer_removeIcon(viewer_icon i)
 *
 * Use
 *  Removes the icon specified.  This routine is real easy!
 *
 * Parameters
 *  viewer_icon i == the icon to remove (they ALL have unique handles, so
 *    this is OK)
 */

void viewer_removeIcon(viewer_icon i);

/*
 * wimp_w viewer_syshandle(viewer v)
 *
 * Use
 *  Returns the WIMP window handle used for the viewer (and much use may it
 *  do you!)
 *
 * Parameters
 *  viewer v == the viewer handle
 *
 * Returns
 *  The wimp_w window handle
 */

wimp_w viewer_syshandle(viewer v);

/*
 * viewer_icon viewer_iconFromCoords(viewer v,int x,int y)
 *
 * Use
 *  Given a set of (absolute) coordinates, this returns the icon in the
 *  viewer specified that the point is on.  This is mainly useful for menu 
 *  maker routines, which will want to be able to select items and so on.
 *
 * Parameters
 *  viewer v == the viewer handle
 *  int x == the x-coordinate of the point
 *  int y == the y-coordinate of the point
 *
 * Returns
 *  The icon handle, or viewer__NOICON if there isn't one.
 */

viewer_icon viewer_iconFromCoords(viewer v,int x,int y);

/*
 * void viewer_iconToCoords(viewer_icon i,wimp_box *box)
 *
 * Use
 *  Calculates the bounding box of the icon given.  If there is an error,
 *  nothing is written in the block.
 *
 * Parameters
 *  viewer_icon i == the icon we're interested in
 *  wimp_box *box == where to store the coordinates
 */

void viewer_iconToCoords(viewer_icon i,wimp_box *box);

/*
 * BOOL viewer_isSelected(viewer_icon i)
 *
 * Use
 *  Returns whether an icon is selected or not.
 *
 * Parameters
 *  viewer_icon i == the icon handle
 *
 * Returns
 *  TRUE if the icon is selected, or FALSE otherwise.
 */

BOOL viewer_isSelected(viewer_icon i);

/*
 * void viewer_selectIcon(viewer_icon i,BOOL onOrOff)
 *
 * Use
 *  Selects or deselects the icon specified.
 *
 * Parameters
 *  viewer_icon i == the icon handle
 *  BOOL onOrOff == TRUE to select, FALSE to deselect
 */

void viewer_selectIcon(viewer_icon i,BOOL onOrOff);

/*
 * viewer viewer_iconToViewer(viewer_icon i)
 * 
 * Use
 *  Returns the viewer in which an icon is contained.
 *
 * Parameters
 *  viewer_icon i == the icon handle
 *
 * Returns
 *  The viewer handle.
 */

viewer viewer_iconToViewer(viewer_icon i);

/*
 * void *viewer_iconHandle(viewer_icon i)
 *
 * Use
 *  Returns the handle attached to the icon when it was created
 *
 * Parameters
 *  viewer_icon i == the icon in question
 *
 * Returns
 *  The handle attached
 */

void *viewer_iconHandle(viewer_icon i);

/*
 * char *viewer_textOfIcon(viewer_icon i)
 *
 * Use
 *  Returns the text of the icon given.
 *
 * Parameters
 *  viewer_icon i == the icon
 *
 * Returns
 *  Pointer to the string (read only!).
 */

char *viewer_textOfIcon(viewer_icon i);

/*
 * int viewer_selected(viewer v)
 *
 * Use
 *  Informs caller how many icons are selected.
 *
 * Parameters
 *  viewer v == the viewer handle
 *
 * Returns
 *  The number of icons selected.
 */

int viewer_selected(viewer v);

/*
 * int viewer_icons(viewer v)
 *
 * Use
 *  Returns the number of icons in a viewer.
 *
 * Parameters
 *  viewer v == the viewer
 *
 * Returns
 *  The number of icons.
 */

int viewer_icons(viewer v);

/*
 * void viewer_doForIcons
 * (
 *   viewer v,
 *   BOOL onlySelected,
 *   void (*proc)(viewer_icon i,void *handle)
 * )
 *
 * Use
 *  Does the same thing for either all the icons in a viewer, or just the
 *  selected ones.
 *
 * Parameters
 *  viewer v == the viewer handle
 *  BOOL onlySelected == whether you want to handle just the selected ones,
 *    or the whole lot.
 *  void (*proc)(viewer_icon i,void *handle) == the routine to do whatever
 *    it is you want to do.
 */

void viewer_doForIcons
(
  viewer v,
  BOOL onlySelected,
  void (*proc)(viewer_icon i,void *handle)
);

/*
 * void viewer_selectAll(viewer v,BOOL onOrOff)
 *
 * Use
 *  Selects or deselects all the icons in a viewer.
 *
 * Parameters
 *  viewer v == the viewer handle
 *  BOOL onOrOff == whether you want the icons to be on or off
 */

void viewer_selectAll(viewer v,BOOL onOrOff);

/*
 * void viewer_clickSelect(viewer v,viewer_icon i,wimp_bbits b)
 *
 * Use
 *  Handles a click on an icon just like clicks in Filer windows.
 *
 * Parameters
 *  viewer v == the viewer handle
 *  viewer_icon i == the icon that was clicked
 *  wimp_bbits b == the mouse button status
 */

void viewer_clickSelect(viewer v,viewer_icon i,wimp_bbits b);

/*
 * char *viewer_menuItem(viewer v,char *header)
 *
 * Use
 *  Returns a menu item of the form either "~<header> ''", 
 *  "<header> '<icon name>'", or "Selection", for inclusion in a menu 
 *  string.
 *
 * Parameters
 *  viewer v == the viewer handle
 *  char *header == the header for the menu item
 *
 * Returns
 *  A pointer to a read-only string.
 */

char *viewer_menuItem(viewer v,char *header);

/*
 * void viewer_setupMenu(viewer v,char *header,menu m,int i,char *buff)
 *
 * Use
 *  Writes a menu item out as for the previous routine, but implants it
 *  directly into the menu, so you don't need to fiddle about with things
 *  like that, and also means that the menu pointer changes.  The menu item
 *  must have been previously set up with menu_redirectItem.  This call will
 *  also set the menu to the correct width.  However, ensure that you call
 *  menu_minWidth(m,0) before fiddling with the width!
 *
 * Parameters
 *  viewer v == the viewer handle pertaining to this request
 *  menu m == the menu to doctor
 *  int i == the menu item
 *  char *buff == where the menu item wants the data
 */

void viewer_setupMenu(viewer v,char *header,menu m,int i,char *buff);

/*
 * viewer_icon viewer_firstSelected(viewer v)
 *
 * Use
 *  Returns the handle of the first selected icon.
 *
 * Parameters
 *  viewer v == the viewer handle
 *
 * Returns
 *  A handle to the first one, or viewer_NOICON.
 */

viewer_icon viewer_firstSelected(viewer v);

/*
 * void viewer_settitle(viewer v,char *title)
 *
 * Use
 *  Changes a viewer's title, so that the extent is updated as well.
 *
 * Parameters
 *  viewer v == the viewer handle
 *  char *title == the new title string
 */

void viewer_settitle(viewer v,char *title);

/*
 * void viewer_dragSelected(viewer_icon icn,wimp_bbits b)
 *
 * Use
 *  Drags a set of icons around a window.
 *
 * Parameters
 *  viewer_icon icn == the viewer icon handle
 *  wimp_bbits b == the button types that started this lot off
 */

void viewer_dragSelected(viewer_icon icn,wimp_bbits b);

/*
 * void viewer_exportSelected
 * (
 *   viewer_icon icn,
 *   wimp_bbits b,
 *   int filetype,
 *   viewer_saveproc save,
 *   viewer_sendproc send,
 *   viewer_printproc print
 * )
 *
 * Use
 *  Allows you to export the data connected with each selected icon to 
 *  another application.  The filename used is the icon's text.
 *
 * Parameters
 *  viewer_icon icn == the icon on which the user clicked to start the drag
 *    operation.
 *  wimp_bbits b == the mouse buttons which started this up.
 *  int filetype == the filetype of the data.
 *  viewer_saveproc save == the save routine (saving and <Wimp$Scrap> 
 *    transfer.
 *  viewer_sendproc send == the send routine (RAM transfer).
 *  viewer_printproc print == the print routine (printing etc.)
 */

void viewer_exportSelected
(
  viewer_icon icn,
  wimp_bbits b,
  int filetype,
  viewer_saveproc save,
  viewer_sendproc send,
  viewer_printproc print
);

/*
 * viewer_icon viewer_helpIcon(viewer v)
 *
 * Use
 *  Informs the caller which icon the Help system is interested in.
 *
 * Parameters
 *  viewer v == the viewer handle
 *
 * Returns
 *  The icon's handle (or maybe viewer_NOICON)
 */

viewer_icon viewer_helpIcon(viewer v);

#endif