home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 594a.lha / IP_Interface_example / readme < prev    next >
Text File  |  1992-01-03  |  6KB  |  137 lines
  1. :-------------------------------------------------------------------------:
  2. : Black Belt Systems Public Interface example code with PROGRESS bar      :
  3. : for use with Imagemaster, Image Professional, or Imagemaster F/c        :
  4. :                   Last Update: January 1st, 1991                        :
  5. :                Revision Level: 1.00                                     :
  6. :                       Authors: Barry Chalmers, Ben Williams             :
  7. :-------------------------------------------------------------------------:
  8.  
  9.   This archive contains everything needed to create a Public Interface
  10.   module that performs a "negative" function upon the area selected by
  11.   the user. This module is intended ONLY for developers; the image
  12.   processors already have a negative function.
  13.   
  14.   This code in this example shows you how to:
  15.   
  16.     - Perform an operation upon a specific buffer
  17.     - Accept an interactive area specification from the user
  18.     - Display messages to the user on the control panel
  19.     - Display a "progress indicator" for the operation
  20.  
  21. Archive Contents:
  22. -----------------
  23. neg.rexx          The ARexx routine for the Negative example
  24. negative          The executable Public Interface module
  25. readme            This README file
  26. makefile          An example make file for the NEGATIVE example
  27. negative_list     An example link list for the NEGATIVE example
  28. negative.c        The source code for the NEGATIVE example
  29. vbar.o            The VBAR routines (object code)
  30. mem.o             More functions required by VBAR routines (object code)
  31.  
  32.   To run the example Public Interface module, 
  33.   
  34.      (1) Copy negative to c:
  35.      (2) Copy neg.rexx to rexx:
  36.      
  37.      (3) Run the image processor, load an image,
  38.          and run the macro "rexx:neg.rexx"
  39.                    
  40.      You will then be asked to identify an area.  A progress
  41.      bar will be displayed and then the changed area will be
  42.      redisplayed.
  43.  
  44. -----------------------------------------------------------------
  45.  
  46.                            ==========
  47.                   Developer Information: CODING
  48.                            ==========
  49.  
  50.   VBAR.o is an object module that developers of Public Interface
  51.   modules for the Imagemaster series can link with. It provides
  52.   a graphical progress display on the Imagemaster gadget screen.
  53.   MEM.o is also required by the VBAR routines.
  54.  
  55.   The jackin structure that gets passed from Imagemaster is
  56.   formulated as follows in IM 1.11, IMFC 3.11 and IP 6.11:
  57.  
  58.     struct jackin
  59.       {
  60.         struct jackinbuff *primary;   /* Points to Primary buffer structure */
  61.         struct jackinbuff *secondary; /* Points to Secondary buffer struct  */
  62.         struct jackinbuff *undo;      /* Points to UnDo buffer struct       */
  63.         struct jackinbuff *blend;     /* Points to Blend buffer struct      */
  64.         struct jackinbuff *brush;     /* Points to Brush buffer struct      */
  65.         unsigned char     *mask;      /* Points to Primary Mask             */
  66.         char              jack[4];    /* 'J' 'A' 'C' 'K'                    */
  67.         struct Screen     *IMscr;     /* Points to control panel screen     */
  68.         unsigned char     pname[4];   /* Program name 'IP'00 'IM'00 'IMFC'  */
  69.         short             ver[2];     /* Program version (major:minor)      */
  70.       };
  71.  
  72.   One of the new additions is 'IMscr' which is a pointer to the
  73.   Imagemaster gadget screen. This is required in the PROGRESS
  74.   routines. You should not use it except as the example shows, or
  75.   you may trash the user's control panel.
  76.  
  77.  
  78.   The following routines are available in the vbar.o object module
  79.   ================================================================
  80.  
  81.   int beginvbars(  struct Screen *IMscr );
  82.   ----------------------------------------
  83.     This needs to be called once only before any VBAR routines are
  84.     called.  It returns 0 if successful and non-zero if unsuccessful.
  85.  
  86.   int progressset(int n,char *text);    or
  87.   int progressaset(int n,char *text);
  88.   -----------------------------------
  89.     This opens a progress window on the Imagemaster gadget screen with
  90.     the text as a label for the progress bar, prepared to display 'n'
  91.     steps. The 'progressaset()' routine gives the new window a close
  92.     gadget.  This routine returns 0 if successful and non-zero if
  93.     unsuccessful. If you use 'progressaset()' to get a close gadget,
  94.     then you must check the return code from 'progressupd()' to see if
  95.     the user has actually pressed the close gadget.
  96.   int progressupd(int i);
  97.   -----------------------
  98.     This draws the progress bar 'i' steps across. The value 'i' must
  99.     not be larger than the total number of steps passed in
  100.     'progressset()'.  It normally returns 0, but will return 1 if the
  101.     progress bar was initiated with 'progressaset()' and the close
  102.     button was pressed by the user.
  103.   
  104.   void progressend();
  105.   -------------------
  106.     This closes the progress window.
  107.  
  108.   void imes( char *string1, char *string2);
  109.   -----------------------------------------
  110.     This displays a message made up of two text strings.  The text
  111.     strings will be truncated if they are too large.  If the second
  112.     string is a null pointer, the default text "-Click Here to
  113.     Continue-" will be displayed on the second line.
  114.  
  115.   void endvbars();
  116.   ----------------
  117.     This should be called when no more progress bars or messages are
  118.     going to be displayed. You cannot use any of the routines provided
  119.     once you have called this routine!
  120.  
  121.  
  122.   The calling sequence is as follows:
  123.   
  124.   
  125.                   /---- beginvbars(  struct Screen *IMscr );
  126.                  |
  127. All progress and |  may       /--  progressset(int n,char *text);
  128.  message calls   |  be       |     progressupd(int i); /* i= 0 to n */
  129. must be between  |  repeated  \--  progressend();
  130. 'beginvbars()'   |
  131.      and         |  anytime   [--  imes( char *string1, char *string2);
  132.  'endvbars()'    |
  133.                   \---- endvbars();
  134.  
  135. See the example P.I. module NEGATIVE.c for actual source code that
  136. uses the VBAR calls in the proper manner.
  137.