function user_def

% function user_def
%
% This function is used in conjunction with FD3.  It is used to allow the
% user to place a user-defined module on the screen.  To do so, the user must
% give the name of an m-file which contains the proper instructions.  Creation
% of such an m-file requires a rudimentary understanding of Matlab's Handle
% Graphics.
%
% ############################################################################
%
% An m-file for creating modules must have the following features:
%
% First of all the function must return a 15 element horizontal vector.  The
% elements should be defined in the following way:
%
% data(1)  <=> handle of PRIMARY OBJECT
% data(2)  <=> either 0 or the handle of a TEXT LABEL OBJECT
% data(3)  <=> either 0 or the handle of a SECONDARY OBJECT
% data(4)  <=> x coord of center
% data(5)  <=> y coord of center
% data(6)  <=> number of arguments required to create module
% data(7)  <=> 0 or the second argument for a two or three-click object
% data(8)  <=> 0 or the third argument for a three-click object
% data(9)  <=> number of times object has been rotated 90 degrees CCW
% data(10) <=> angle defining top-right corner     ( 0      < theta < pi/2   )
% data(11) <=> angle defining top-left corner      ( pi/2   < theta < pi     )
% data(12) <=> angle defining bottom-left corner   ( pi     < theta < 3*pi/2 )
% data(13) <=> angle defining bottom-right corner  ( 3*pi/2 < theta < 2*pi   )
% data(14) <=> X scaling factor
% data(15) <=> Y scaling factor
%
% ############################################################################
%
% It is useful to first define PRIMARY OBJECT, TEXT LABEL OBJECT, and
% SECONDARY OBJECT.  PRIMARY OBJECTS are line objects.  For simple modules
% like mixers and settlers, the PRIMARY OBJECT contains all the data which is
% used to draw the module.  Streams may only be connected to the PRIMARY
% OBJECT part of a module.  The TEXT LABEL OBJECT is a text object.  It is
% the graphics object which is used to label the module.  Like PRIMARY
% OBJECTS, SECONDARY OBJECTS are line objects.  Streams cannot, however, be
% connected to SECONDARY OBJECTS.  Hence, modules only have SECONDARY OBJECTS
% if it is inappropriate to attach a stream to some portion of the module
% (the arrow on a compressor, the sawtooth wave on a heat exhanger, the
% inside lines on a kiln, the base on a pump, etc.) 
%
% ############################################################################
%
% Because of the way FD3 is programmed, PRIMARY OBJECTS should be shaped so
% that any horizontal or vertical ray drawn from the center will cross the
% PRIMARY OBJECT exactly once.  For instance, the following shapes with
% centers "0" could not be used for PRIMARY OBJECTS:
%
%         **************************
%          *                       *
%           *                      *
%            *                     *
%             ***                  *
%        ***    ***                *
%        * ***    *   0            *
%        *   ******                *
%        *                         *
%        ***************************
%
%
%             *********************
%             *                   *
%             ************        *
%                        *        *
%                     0  *        *
%                        *        *
%             ************        *
%             *                   *
%             *********************
%
% The latter of these two objects would be valid, however, if it were shifted
% with respect to the center.
%
%       *********************
%       *                   *
%       ************        *
%                  *        *
%                  *  0     *
%                  *        *
%       ************        *
%       *                   *
%       *********************
%
%
% Note the following:
%
%     ##############################################################
%     # The PRIMARY OBJECT *MUST* be drawn on FD3AXES(3).  FD3AXES #
%     # is a global variable defined by FD3.  You *MUST* declare   #
%     # FD3AXES global at the beginning of your m-file.            #
%     ##############################################################
%
%
% The PRIMARY OBJECT may have NaN's in it's Xdata and Ydata, but great care
% should be taken.  See f_evap for an example of how NaN's may be used.
%
% ############################################################################
%
% If your module returns 0 for data(2), FD3 will ask the user to give the
% module a label.  Most of the time, however, objects come with labels.
% Labels should be created with the nice_txt command.
%
% Note the following:
%
%     ########################################################
%     # The TEXT LABEL OBJECT *MUST* be drawn on FD3AXES(2). #
%     ########################################################
%
% ############################################################################
%
% SECONDARY OBJECTS have no restrictions as to their shape or as to the use of
% NaN's.
%
% Note the following:
%
%     ####################################################
%     # SECONDARY OBJECTS *MUST* be drawn on FD3AXES(1). #
%     ####################################################
%
% ############################################################################
%
% In general, it is ALWAYS preferable to create the SECONDARY OBJECT, if
% present, first, the TEXT LABEL OBJECT, if present, next, and the PRIMARY
% OBJECT, if present, last.  If the objects are ot created in this order,
% FD3 must go through some extra steps to make sure that the stacking order
% of the graphics is correct.
%
% ############################################################################
%
% ANGLES
%
% The four angles are very important because they allow FD3 to tell whether
% or not the user has clicked on the top, bottom, left, or right side of a
% module (the program which automatically creates alternating horizontal /
% vertical streams uses this information).  If the center of the object is
% "0", angles are defined as follows:
%
%                       pi/2
%
%                        |      /
%                        |     /
%                        |    /
%                        |   /
%                        |  /
%                        | /    
%                        |/ theta 
%       pi --------------+--------------- 0
%                        |
%                        |
%                        |
%                        |
%                        |
%                        |
%
%                      3*pi/2
%
% If data(11) >= theta > data(10), the click registers as on the top.
% If data(12) >= theta > data(11), the click registers as on the left.
% If data(13) >= theta > data(12), the click registers as on the bottom.
% Else, the click registers as on the right.
%
% FD3 automatically updates these angles when the X and Y Scaling Factors
% change and when the module is rotated.
%
% ############################################################################
%
% ROTATION, X SCALING FACTOR, Y SCALING FACTOR
%
% The number of CCW rotations the object has undergone is generally initially
% set to 0, although there is no reason it need be.  The X and Y Scaling
% Factors are both normally initiallyized to 1.  Once again, however, this is
% is not required.
%
% ############################################################################
%
% NUMBER OF ARGUMENTS
%
% 

global FD3NEXT FD3MESSAGE

set_menu(1:6,'Off')

wflag=1;

while wflag

   [FD3NEXT,flag]=di_inp_c('What is the m-file?','',0);

   if flag
      di_warn('','User-Defined Module Cancelled','CONTINUE')
      fd_reset(0)
      return
   end

   len=length(FD3NEXT);

   if len>2
      if FD3NEXT((len-1):len)=='.m'
         FD3NEXT=FD3NEXT(1:len-2);
      end
   end

   if exist([FD3NEXT '.m'])==2
      wflag=0;
   else
      di_warn('FILE ERROR','That m-file does not exist!','CONTINUE')
   end

end

adj_menu;

FD3MESSAGE=di_mssg('Point and|click on the|center of the|new module.');


