home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 2 / goldfish_vol2_cd1.bin / files / util / wb / picicon / doc / picicon.doc next >
Text File  |  1994-04-04  |  18KB  |  552 lines
  1.                PicIcon 1.03 - Icon Image Generator
  2.  
  3. Table of Contents
  4.  
  5.    1.0 Introduction
  6.    2.0 Copyright
  7.    3.0 Using PicIcon
  8.        3.1 CLI Startup
  9.        3.2 Workbench Startup
  10.            3.2.1 Tooltypes
  11.    4.0 Hints and Tips
  12.    5.0 Note for Workbench 3.0
  13.    6.0 Limitations
  14.    7.0 Bug reports
  15.    8.0 Change History
  16.    9.0 Acknowledgments
  17.       
  18.  
  19. 1. Introduction
  20.  
  21. PicIcon takes an IFF image file, both ILBM and ANIM formats are supported,
  22. and creates an icon image showing the contents of the file. This allows
  23. images to be more easily recognised from the Amiga Workbench.
  24.  
  25. PicIcon be used from both the CLI and Workbench, although it is more suited
  26. to the Workbench environment with some functions only being available via
  27. Workbench.
  28.  
  29. PicIcon is distributed as shareware. This version is fully functional
  30. however a requester saying that is not registered will appear after
  31. a number of files have been processed. See the copyright section for
  32. details on how to register.
  33.  
  34. PicIcon requires AmigaDOS 2.04 (V37) or later to run.
  35.  
  36.  
  37. 2. Copyright
  38.  
  39.                   PicIcon release 1.03
  40.  
  41. PicIcon 1.03 and PicIcon project icon (hereinafter "Files") and
  42. their related documentation and examples
  43. (c) Copyright 1994 Michael J. Sheppard. All Rights Reserved.
  44.  
  45. This version of PicIcon is shareware. Permission is given to distribute
  46. these Files freely via any means which preserves its copyrights. The
  47. Files may not be sold for profit. Any distribution must include both
  48. the PicIcon License file and the PicIcon documentation drawer complete
  49. with contents.
  50.  
  51. The registered version of PicIcon contains the full source code and
  52. removes the shareware message from it's operation. To register send
  53. 10 UK pounds, or $15 US, to ;
  54.  
  55.    PicIcon Registration.
  56.    M.J.Sheppard
  57.    163, Sapgate Lane,
  58.    Thornton
  59.    Bradford
  60.    BD13 3DY
  61.  
  62. If you include an Internet email address with your registration then I
  63. will keep you informed of updates to PicIcon and their availability. 
  64.  
  65. These Files and their related documentation and examples are provided
  66. "AS-IS" and subject to change without notice; no warranties are made.
  67. All use is at your own risk. No liability or responsibility is
  68. assumed.
  69.  
  70.  
  71. 3. Using PicIcon
  72.  
  73. PicIcon can be started from either the Workbench or CLI.
  74.  
  75. PicIcon has two modes of operation. It can either try and match the colours
  76. in the file with those currently in use by Workbench, or just assign colours
  77. on a modular basis i.e. Areas in colour 1 in the file appear as colour 1 in
  78. the icon. For any file whose image has greater than 256 colours PicIcon will
  79. always try to match the colours. For images with fewer than 256 colours the
  80. method used can be set by the user via the match colours checkbox on the
  81. settings window.
  82.  
  83. When matching colours PicIcon looks for the nearest colour based on colour
  84. intensity. This can result is some unexpected colour choices. For example
  85. for a greyscale image PicIcon may introduce some colour in the icon this is
  86. because there aren't enough greys in the Workbench palette to match all of
  87. the colours to a grey. More information about PicIcons colour matching can
  88. be found in the Hints and Tips section of this document.
  89.  
  90.  
  91. 3.1 CLI Startup
  92.  
  93. PicIcon processes all of the files listed on the command line and exits.
  94. If an error is detected when processing a file then PicIcon will continue
  95. to the next file if possible.
  96.  
  97. The command template for PicIcon is as follows;
  98.    
  99. PicIcon FILES/M,SETTINGS/K,WIDTH/K/N,HEIGHT/K/N,DEPTH/K/N,QUIET/S,ALL/S
  100.  
  101.    FILES/M
  102.  
  103.    A list of files to create icon images for. if this is an AmigaDOS pattern
  104.    PicIcon will process all files that match the pattern.
  105.              
  106.    E.g.
  107.      PicIcon  #?.ham
  108.             
  109.      Will create icon images for all files in the current drawer having
  110.      names ending in '.ham'.
  111.  
  112.    SETTINGS/K
  113.  
  114.    This is the name of a file containing PicIcon settings to use
  115.    when processing the files. New settings files can be created
  116.    using the Settings window.
  117.  
  118.    If this parameter is not present then PicIcon will load the
  119.    default settings file, S:PicIcon.config.
  120.  
  121.    WIDTH/K/N
  122.  
  123.    This is the width, in pixels, of the icons created by PicIcon.
  124.    This value overrides the value stored in the settings file. 
  125.    Default = 48
  126.  
  127.    HEIGHT/K/N
  128.  
  129.    This is the height, in pixels, of the icons created by PicIcon.
  130.    This value overrides the value stored in the settings file.
  131.    Default = 20
  132.  
  133.    DEPTH/K/N
  134.  
  135.    This is the depth, in planes, of the icons created by PicIcon.
  136.    This value overrides the value stored in the settings file.
  137.    This effects the number of colours used in the icons and can
  138.    be 2, 3 or 4 for 4, 8 or 16 colours respectively.
  139.    Default = 3 ( 8 colours ).
  140.  
  141.    Note: Under Workbench 3.0 the choice of icon depth is limited
  142.      to 2 or 3 giving 4 or 8 colours only. This is due to the
  143.      change in colour handling introduced for Workbench 3.0.
  144.  
  145.    QUIET
  146.  
  147.    By default PicIcon displays the names of the files as it processes
  148.    them.  Setting this flag stops PicIcon from displaying this
  149.    information.
  150.  
  151.    ALL
  152.  
  153.    This flag causes PicIcon to process all of the files in the
  154.    directories specified in the FILES argument, including any
  155.    subdirectories that they might have.   
  156.  
  157.  
  158. 3.2 Workbench Startup
  159.       
  160. To start PicIcon from Workbench double-click on the PicIcon icon with the
  161. left mouse button. After a few seconds an application icon will appear on
  162. the Workbench. 
  163.  
  164. PicIcon recognises an number of tooltypes to modify it's operation;
  165. SETTINGS, WIDTH, HEIGHT, DEPTH, QUIET, FONT and FONTSIZE. These are
  166. described in detail below.
  167.  
  168. To create an image drag the icon of a file onto the application icon and
  169. release the mouse button. PicIcon will then process the file and create
  170. an icon image.
  171.  
  172. If you double-click on the application icon a window is displayed allowing
  173. you to change the current settings used to create icons.
  174.  
  175. To stop PicIcon either double-click on the PicIcon disk icon, or select the
  176. quit item on the settings window menu bar.
  177.  
  178. 3.2.1 Tooltype descriptions
  179.  
  180.    SETTINGS=<filename>
  181.  
  182.    This is the name of a file containing PicIcon settings to use
  183.    when processing the files. New settings files can be created
  184.    using the Settings window.
  185.  
  186.    If this parameter is not present then PicIcon will load the
  187.    default settings file, S:PicIcon.config.
  188.  
  189.    WIDTH=<pixels>
  190.  
  191.    This is the width, in pixels, of the icons created by PicIcon.
  192.    This value overrides the value stored in the settings file. 
  193.    Default = 48
  194.  
  195.    HEIGHT=<pixels>
  196.  
  197.    This is the height, in pixels, of the icons created by PicIcon.
  198.    This value overrides the value stored in the settings file.
  199.    Default = 20
  200.  
  201.    DEPTH=<planes>
  202.  
  203.    This is the depth, in planes, of the icons created by PicIcon.
  204.    This value overrides the value stored in the settings file.
  205.    This effects the number of colours used in the icons and can
  206.    be 2, 3 or 4 for 4, 8 or 16 colours respectively.
  207.    Default = 3 ( 8 colours ).
  208.  
  209.    QUIET
  210.  
  211.    By default PicIcon displays a window showing the progress is it
  212.    making processing each file. This option stops this window appearing.
  213.    This can be overridden using the Quiet option on the Settings menu.
  214.  
  215.    FONT <name>
  216.  
  217.    PicIcon uses the system default font for all windows. This option
  218.    allows you to specify a particular font to use for the windows.
  219.  
  220.    The FONTSIZE tooltype should be used to set the size of the font.
  221.  
  222.    FONTSIZE <pixels>
  223.  
  224.    This tooltype allows you to set the size of the font given in the
  225.    FONT tooltype.
  226.  
  227.    Settings Window
  228.  
  229.    The settings window allows you to modify the current settings used to create
  230.    icon images. It is activated by double-clicking on the PicIcon application
  231.    icon. The effects of the changes are controlled by the three buttons at the
  232.    bottom of the window, Save, Use, and Cancel. No changes made to the window
  233.    will have any effect on the creation of images until one of these three
  234.    buttons is pressed.
  235.  
  236.    The settings that can be changed from this window are ;
  237.  
  238.    Width:
  239.  
  240.    Gadget Type  : Slider   
  241.    Value range  : 20 - 80 pixels
  242.    Shortcut key : w
  243.  
  244.    This gadget allows you to change the width of the icons produced. When making
  245.    changes to the dimensions of the icon you should consider the dimensions of
  246.    the original image to limit to amount of distortion in the resultant icon.
  247.                
  248.    Height:
  249.  
  250.    Gadget Type  : Slider   
  251.    Value range  : 10 - 40 pixels
  252.    Shortcut key : h
  253.  
  254.    This gadget allows you to change the height of the icons produced. When making
  255.    changes to the dimensions of the icon you should consider the dimensions of
  256.    the original image to limit to amount of distortion in the resultant icon.
  257.  
  258.    Colours:
  259.  
  260.    Gadget Type  : Slider   
  261.    Value range  : 4,8, or 16* colours
  262.    Shortcut key : l
  263.  
  264.    This gadget allows you to change the number of colours in the resultant icon
  265.    image. When selecting this bear in mind the number of colours that you normally
  266.    use for your Workbench screen.
  267.  
  268.    *: Under Workbench 3.0 the option for 16 colours is not available.
  269.  
  270.    Border:
  271.  
  272.    Gadget Type  : Checkbox
  273.    Shortcut key : b
  274.  
  275.    If this is checked then PicIcon will draw a box around the resultant image
  276.    making it appear that icon has a border around it. PicIcon takes advantage
  277.    of the Workbench 3D icons to produce a border with a minimum loss of image.
  278.  
  279.    Match Colours:
  280.  
  281.    Gadget Type  : Checkbox
  282.    Shortcut key : m
  283.  
  284.    If this gadget is checked then PicIcon will attempt to match the colours in
  285.    the image to those currently in use by Workbench. For images with more than
  286.    256 colours PicIcon ignores this and matches the colours anyway.
  287.  
  288.    Free Position:
  289.  
  290.    Gadget Type  : Checkbox
  291.    Shortcut key : p
  292.  
  293.    If this box is checked then PicIcon 'UnSnapshots' the icon allowing
  294.    Workbench to position it appropriately. This is useful if the size
  295.    of the icon is changed.
  296.  
  297.    Replace Tool:
  298.  
  299.    Gadget Type  : Checkbox
  300.    Shortcut key : r
  301.  
  302.    If this gadget is checked, and a default tool is given, PicIcon will
  303.    replace the default tool in the icon with that defined. Otherwise
  304.    PicIcon will only replace the default tool if the icon previously had
  305.    no tool defined.
  306.  
  307.    Default Tool:
  308.  
  309.    Gadget Type  : String
  310.    Maximum size : 128 characters
  311.    Shortcut key : t
  312.  
  313.    This string is the name of the program to execute when the icon created
  314.    is double clicked. How the value is used depends on the setting of the
  315.    Replace Tool gadget.
  316.  
  317.    Tooltypes:
  318.  
  319.    Gadget Type  : Listview
  320.    Shortcut key : none
  321.  
  322.    The tooltypes used when creating an icon are displayed in the listview gadget,
  323.    these are only used when PicIcon sets the default tool of the icon it has
  324.    created an image for.
  325.  
  326.    It is not possible to edit the values in the listview directly so this has to
  327.    be done using the New and Del gadgets. These allow tooltypes to be added and
  328.    deleted from the list respectively.
  329.  
  330.    New:
  331.  
  332.    Gadget Type  : Button
  333.    Shortcut key : n
  334.  
  335.    Pressing this button adds a new tooltype to the list of tooltypes. It allows
  336.    you to type in the value of this tooltype into the string gadget to the left
  337.    of the New and Del buttons. Each tooltype can be up to 128 characters long.
  338.  
  339.    Del:
  340.  
  341.    Gadget Type  : Button
  342.    Shortcut key : d
  343.  
  344.    Pressing this button deletes the currently selected tooltype from the list
  345.    of tooltypes. This button is only enabled if you have a tooltype selected.
  346.  
  347.    Save:
  348.  
  349.    Gadget Type  : Button
  350.    Shortcut key : s
  351.  
  352.    This button causes the settings in the window to be made the current
  353.    ones used by the program and saves those settings to the default settings
  354.    file. It also exits from the settings window.
  355.  
  356.    Use:
  357.  
  358.    Gadget Type  : Button
  359.    Shortcut key : u
  360.  
  361.    This button exits from the settings window and makes the settings displayed
  362.    in the window the current settings.
  363.  
  364.    Cancel:
  365.  
  366.    Gadget Type  : Button
  367.    Shortcut key : c
  368.     
  369.    When this button is pressed the settings window is removed and all changes
  370.    made are abandoned.
  371.  
  372. Whilst the window is active PicIcon installs a menu bar allowing a number
  373. of extra features to be selected. The menu consists of the following options ;
  374.    
  375. Project menu
  376.  
  377.    Create Icon
  378.  
  379.    Shortcut Key: Amiga C
  380.  
  381.    The option displays an ASL file requester allowing you to select a number
  382.    of files to create icons for. Selecting the OK button on the file requester
  383.    causes PicIcon to process all of the files selected.
  384.  
  385.    If changes have been made to the values in the settings window they are not
  386.    taken into account when creating the new images.
  387.  
  388.    About
  389.  
  390.    Shortcut key: Amiga ?
  391.  
  392.    A requester is displayed showing information about PicIcon. This includes the
  393.    version number of the PicIcon being run.
  394.  
  395.    Quit
  396.  
  397.    Shortcut key: Amiga Q
  398.  
  399.    Selecting this menu option causes PicIcon to exit.
  400.  
  401. Settings menu
  402.  
  403.    Quiet
  404.  
  405.    Shortcut key: none
  406.  
  407.    This menu option toggles whether the progress window is displayed when files
  408.    are being processed. If the tick symbol is shown by the option then the
  409.    progress window will not be shown.
  410.  
  411.    The initial setting of this can be set using the QUIET tooltype.
  412.  
  413.    Load Settings
  414.  
  415.    Shortcut key: Amiga L
  416.  
  417.    An ASL file requester is displayed allowing a settings file to be selected
  418.    for loading. Pressing the OK button causes the values in the file to be
  419.    loaded into the window. This will not effect the current settings used by
  420.    PicIcon when creating images until either the Save or Use buttons are selected,
  421.    the loaded values can be removed by selecting the Cancel button.   
  422.  
  423.    Save Settings
  424.  
  425.    Shortcut key: Amiga S
  426.  
  427.    This saves the current values displayed in the window to the default settings
  428.    file S:PicIcon.config. If no Settings tooltype or parameter is given when
  429.    PicIcon is started then these settings will be used whenever PicIcon is run.   
  430.  
  431.    Save Settings As
  432.  
  433.    Shortcut key: Amiga A
  434.  
  435.    This option displays an ASL save requester allowing you to save the values
  436.    displayed in the window to a named settings file. This file can be used in
  437.    future, either by giving it as the settings tooltype or parameter or from
  438.    the Load Settings menu option, to change the values used by PicIcon to create
  439.    images.
  440.       
  441.  
  442. 4. Hints and Tips
  443.  
  444. If you are using a 4 colour Workbench then set PicIcon to not match
  445. colours. There are not enough different display colours available to allow
  446. meaningful colour matching.
  447.  
  448. If you are using an 8 colour Workbench with colour matching adjust the
  449. palette so that you get at least one red, green, blue and yellow. This
  450. will give PicIcon an easier job in trying to match the colours and result
  451. in better, more recognisable icons. An example 8 colour palette is present
  452. in the PicIcon release.
  453.  
  454. If you find that PicIcon is matching colours in an unexpected manner you 
  455. should try and adjust the Workbench palette. If you find that PicIcon is
  456. using changing the colour of an area in the image when a similar colour
  457. is present in the palette try adjusting the RGB values of both palette
  458. colours so that they are similar in intensity. An example of this would
  459. be a dark green area on the image being represented by a dark brown area
  460. on the icon when a light green is present in the palette. To solve this
  461. problem make the green a little darker until the correct result is 
  462. obtained.
  463.  
  464. For complex images try and make the icon image as large as possible. Small
  465. icons of complex pictures look cluttered and are not easily recognisable.
  466.  
  467.  
  468. 5.0 Notes for Workbench 3.0
  469.  
  470. With Workbench 3.0 a number of changes were introduced regarding the way
  471. in which colours are defined and used by Workbench. This can result in
  472. some odd behaviour from PicIcon.
  473.  
  474. For correct operation under Workbench 3.0 you should either create only
  475. 4 colour Icons, in which case PicIcon will use the first 4 colours defined
  476. by Workbench, or use an 8 colour screen mode with 8 colour icons.
  477.  
  478. If you try and create 8 colour icons using a screen mode with more than 8
  479. colours then PicIcon may have problems trying to match with colours 5 to 8.
  480.  
  481.  
  482. 6.0 PicIcon Limitations
  483.  
  484. PicIcon will process all ILBM files with 6 or fewer planes, including HAM
  485. and extra-half brite files. In addition PicIcon will process 24 bit ILBM
  486. files. All ANIM files made up of images of any of the above formats will
  487. also be processed.
  488.    
  489. This version of PicIcon will not process 256 colour or HAM8 files. Also it
  490. will not process 24bit DEEP, NewTek 21bit, HAME or DCTV files.
  491.  
  492.  
  493. 7.0 PicIcon Change History
  494.  
  495.   Version        Change description
  496.  
  497.    1.03        - The Workbench colours are now read directly from the screen
  498.                  rather than the preferences file. This corrected operation
  499.                  under Workbench 3.0. See Notes for Workbench 3.0 above.
  500.                  PicIcon now notices when the palette is changed and updates
  501.                  it's internal colour table accordingly.
  502.                  
  503.    1.02        - The tooltype array used to create the new icon was not NULL
  504.                  terminated causing random errors when trying to add tooltypes
  505.                  to an icon, including infinite updating and spurious tooltype
  506.                  entries. Fixed.
  507.    
  508.    1.01        - Changed name of button used to create a new tooltype from
  509.                  Add to New to be consistent with other programs.
  510.  
  511.                - If PicIcon expects to be able to match colours but there
  512.                  is no CMAP chunk in the ILBM IFF form then a warning is
  513.                  displayed before the file is processed.
  514.  
  515.  
  516.    1.00        - Initial Release.
  517.  
  518.  
  519. 8.0 PicIcon Bug reports
  520.  
  521. If you find a bug in PicIcon or have a file that it will not process then
  522. please contact;
  523.    
  524.    Michael J. Sheppard
  525.    163 Sapgate Lane,
  526.    Thornton.
  527.    Bradford.
  528.    BD13 3DY.
  529.    United Kingdom
  530.       
  531.    Email: mick@genasys.co.uk
  532.  
  533. If the problem is one where you cannot process a file please include details
  534. of the format of the file, if known, and the software used to produce it. The
  535. more information you provide me with the more likely I am to be able to find
  536. an answer.
  537.  
  538.  
  539. 9.0 PicIcon Acknowledgements
  540.  
  541. PicIcon was written and tested on an unaccelerated Commodore Amiga A2000 with
  542. a GVP Series II SCSI controller card and 52MB Quantum Hard Disk.
  543.   
  544. PicIcon was developed using SAS/C 5.10 and the Commodore V37 Native
  545. Developer Kit.
  546.    
  547. The windows were designed using GadToolsBox 2.0. Thanks to Jan van den Baard
  548. of Jaba Development for this very useful product.
  549.    
  550. Thanks to David Sheppard for testing and suggestions.   
  551.  
  552.