home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d1xx / d126 / iconify.lha / Iconify / iconify.doc < prev    next >
Text File  |  1988-01-02  |  4KB  |  105 lines
  1. iconify()        Amiga Programmer's Manual        iconify()
  2.  
  3. NAME
  4.     iconify -- Create an icon on the screen that can be dragged
  5.            around.
  6.  
  7. SYNOPSIS
  8.     #include "iconify.h"
  9.     int        success;
  10.  
  11.     success = 
  12.      iconify (LeftEdge, TopEdge, Width, Height, Screen, ptr, Type);
  13.     UWORD        *LeftEdge, *TopEdge;
  14.     UWORD        Width, Height;
  15.     struct Screen    *Screen;
  16.     APTR        ptr;
  17.     int        Type;
  18.  
  19. DESCRIPTION
  20.     Iconify() is a subroutine that creates an icon on the Amiga screen
  21.     that can be subsequently dragged around, and double-clicked on.
  22.  
  23.     Iconify() creates an icon at screen location (*LeftEdge, *TopEdge)
  24.     and of size (Width, Height), in pixels.  The icon is created on
  25.     the screen specified.  If Screen is NULL, the icon will be created
  26.     on the WorkBench screen.
  27.  
  28.     The Type variable tells iconify() how to make the icon.  Based on
  29.     the value contained in Type, ptr may be interpreted in one of three
  30.     different ways:
  31.  
  32.     ICON_IMAGE:
  33.         ptr points to an initialized structure of type Image
  34.         (intuition.h).  The image contained in the structure will
  35.         be used as the icon image.
  36.  
  37.     ICON_BORDER:
  38.         ptr points to an initialized structure of type Border
  39.         (intuition.h).  The drawing instructions contained in the
  40.         border structure will be used to render the icon.
  41.  
  42.     ICON_FUNCTION:
  43.         [This is by far the most interesting one.]  ptr points to
  44.         a function that will be called by iconify() N times a
  45.         second (where N is a compile-time constant).  The format
  46.         of the call is:
  47.  
  48.         (* ((void (*)()) ptr)) (win, val);
  49.         struct Window    *win;
  50.         WORD        val;
  51.  
  52.         When the icon is first created, your function will be
  53.         called with val equal to one (non-zero).  This should be
  54.         used as a flag to your function to call any initialization
  55.         code it may need (such as caching the icon size, setting
  56.         draw modes, etc.).  On every subsequent call, val will be
  57.         equal to zero.
  58.  
  59.         win points to the window which is your icon (the icon is in
  60.         fact a window-sized drag gadget).  This may be used for
  61.         rendering purposes (animated icons, for example).
  62.  
  63.     After the icon is created, iconify() will wait until the icon has
  64.     been double-clicked on.  If the icon is of type ICON_FUNCTION,
  65.     iconify() will also call the supplied function N times a second
  66.     while waiting for the double-click.
  67.     
  68.     When the icon is double-clicked, iconify() will update the values
  69.     pointed to by LeftEdge and TopEdge.  This is so that, in subsequent
  70.     invocations of iconify(), the icon will be where the user last left
  71.     it.  Thus, it is the responsibility of the calling program to
  72.     maintain these values.
  73.  
  74.     After updating these values, iconify() will remove the icon from
  75.     the screen, and return to the caller with a non-zero value.  If any
  76.     of iconify()'s internal operations fail, a zero value will be
  77.     returned.  It is strongly suggested that this be checked for by
  78.     the calling program.
  79.  
  80. VIEW TO OUTSIDE PROGRAMS
  81.     Icons created with iconify() will look like small windows (this is
  82.     largely due to the fact that they are small windows).  Outside
  83.     programs may wish to differentiate between 'real' windows, and
  84.     objects created with iconify().
  85.     
  86.     To this end, iconify() writes the 32-bit constant 0x49434f4e
  87.     (which just happens to be the word 'ICON' in ASCII) into the
  88.     window's UserData field.  Outside programs that are manipulating
  89.     windows can check for this so they can avoid touching icons (or so
  90.     that they can specifically find icons if they want).
  91.  
  92. AUTHOR
  93.     Leo L. Schwab
  94.     61 Martens Blvd.
  95.     San Rafael, CA   94901-5028
  96.     {ihnp4!ptsfa,hplabs}!{well!unicom}!ewhac
  97.  
  98. SEE ALSO
  99.     Amiga Rom Kernel Manual
  100.     Intuition: The Amiga User Interface
  101.  
  102. BUGS
  103.     There are NO bugs in MY code.  However, there may be any number
  104.     of undesireable features (but I doubt it).
  105.