                   TRASH - Sample Windows 3.1 Application


                          written by Brent Ethington
             Senior Systems Engineer, Microsoft - Orange County



The Trash application is a sample Windows 3.1 application that demonstrates
the following new concepts that are provided with Windows 3.1:

   Shell Drag/Drop
   Miscellaneous Shell functions
   DDE Management Library
   Multimedia Sound Capability


The purpose for creating this application was to demonstrate some of the new
API functionality provided with Windows 3.1 as well as to help continue to
evangelize the cause to make Windows computing fun.



The Trash application consists of 3 pieces:
   TRASH.EXE      -  Windows 3.1 Application
   TRASHEXT.DLL   -  File Manager Extension DLL
   TRASH.INI      -  INI file that contains TRASH preference settings



****************************
Background - How it Works...
----------------------------


Trash
-----

The TRASH.EXE application is a Windows 3.1 application that is a DDEML server.
Trash supports the Drag/Drop functionality as provide by the new Windows 3.1
Shell APIs, which allows items to be dragged from the File Manager and dropped
onto the Trash icon (or into the Trash window).  Trash adds the names of the
dropped files to a multiple selection listbox, which is used to display the
names of items in the Trash.  This implementation of the Trash doesn't move
any items from the location where they reside on the drive, it simply maintains
a list of the items that a user requests to be deleted.

Items can be removed from the Trash by selecting one or more items in the
listbox and then choosing the 'Return Items to Disk...' menu item (in case
you change your mind about wanting them in the Trash).



TrashExt
--------

The TRASHEXT.DLL File Manager extension adds a 'Trash' item to the File
Manager menu to provide a means of allowing a user to Empty the Trash from
the File Manager.  DDE is used (via the new DDEML provided with Windows 3.1)
to communicate between the TrashExt File Manager extension and the Trash
application.

When the user selects the 'Trash' menu item from the File Manager
menu bar, the TrashExt extension does a DDE query to determine the number of
items present in the Trash - if no items are found, the 'Empty Trash...' menu
item is grayed (preventing the user from selecting it).  If the Trash contains
items, then the TrashExt extension sends a DDE Execute message to the Trash
and the Trash application then processes the '[EmptyTrash]' request.

When the user requests to Empty the Trash, the Trash application first scans
the contents of the Trash to determine the number of items in the Trash
(including any items that are within subdirectories), the size of the items
in the Trash (including any items that are within subdirectories), and whether
any items in the Trash (including any items that are within subdirectories)
that have Read Only or System attributes.

The user is then presented with a dialog box prompting for confirmation to
Empty the Trash.  On the Empty Trash dialog box there is a check box that says
'Really Delete the Item(s)? (i.e., permanently)' - when this checkbox is
Enabled, files are actually DELETED - when this checkbox is NOT enabled, items
are ONLY removed from the Trash.  This checkbox allows the use or demonstration
of this application, WITHOUT actually requiring files to be deleted.  The state
of this checkbox is saved back to the TRASH.INI file as a preference setting
with the TRASH application is terminated - so it can be used as a default on
the next invocation.


Any items in the Trash (or within subdirectories if the item is a subdirectory)
that have Read Only or System attributes will NOT be removed (or deleted) from
the Trash.  To OVERRIDE the warnings or prompts that the Trash application may
display (as well as to OVERRIDE the file attribute settings), press the <Ctrl>
key when selecting the 'Empty Trash...' menu item from the TrashExt extension
menu or from the Trash application.



*****************
What's Planned...
-----------------

-  Change the Trash application so that it displays the icons for items in
   the Trash rather than showing only the name of the item

-  Move the selected item from the location where it resides when dragged from
   the File Manager to another location (i.e., a place where items in the Trash
   are stored), so that they are not longer 'visible' in their original
   location (also allowing them to be put back if desired)




******************
Installation Steps
------------------

   -  Place the TRASH.EXE application in your Windows 3.1 directory (doesn't
      need to be, but it at least needs to be somewhere on your path - if you
      want to execute it from the File Manager [versus from the StartUp group])

   -  Place the TRASHEXT.DLL in the Windows 3.1 directory

   -  Modify the WINFILE.INI file to add the following lines: (if the [AddOns]
      section doesn't exist in the INI file, then create it)
    
         [AddOns]
         Trash Extension=C:\WIN31\TRASHEXT.DLL

      The [AddOns] section informs the File Manager which extension DLLs to
      load - make sure the path specified for the location of the extension
      is correct.

   -  Place (or create) the TRASH.INI file in your Windows 3.1 directory




*******************************
TRASH.INI - Preference Settings
-------------------------------

The TRASH.INI file supports the following headings and switches:

   [Settings]

   DeleteFiles=0     -  Specifies whether Files should actually be Deleted off
                        of the drive when a user requests the Trash to be
                        emptied.  This setting defines the default state.
                        
                        If 'DeleteFiles=0', then files are only removed from
                        the Trash and NOT Deleted from the drive.

                        If 'DeleteFiles=1', then files are Deleted from the
                        drive.

                        DEFAULT: 'DeleteFiles=0' - items NOT deleted.


   ShowScanActivity=1 - Specifies whether Trash activity should be displayed
                        as the Trash application analyzes the items in the Trash.

                        If 'ShowScanActivity=0', then no activity is displayed.

                        If 'ShowScanActivity=1', then activity is displayed as
                        the Trash processes the items in the Trash.

                        DEFAULT: 'ShowScanActivity=1' - Trash activity displayed.



   [Icons]

   EmptyTrash=       -  Identifies the path and filename of an icon file (.ICO)
                        that should be used to represent the EmptyTrash state
                        of the Trash application when the Trash is minimized.

                        If this switch isn't present or the specified icon
                        file doesn't exist, then the default EmptyTrash icon
                        is used.

                        EXAMPLE:    EmptyTrash=EMPTYNUK.ICO


   FullTrash=        -  Identifies the path and filename of an icon file (.ICO)
                        that should be used to represent the FullTrash state
                        of the Trash application when the Trash is minimized.

                        If this switch isn't present or the specified icon
                        file doesn't exist, then the default FullTrash icon
                        is used.

                        EXAMPLE:    FullTrash=FULLNUKE.ICO



   [Sounds]

   PlaySounds=0      -  Specifies whether Trash should use the Multimedia
                        sound capabilities of Windows 3.1.

                        If 'PlaySounds=0', then no sound effects will be used.

                        If 'PlaySounds=1', then sound effects will be played
                        when the user drops an item (or items) into the Trash
                        and when the user empties the Trash.

                        DEFAULT: 'PlaySounds=0' - No sound effects will be
                                                  played.


   DropSound=        -  Identifies the FULL path and filename of a Multimedia
                        Wave (.WAV) Audio file that should be played when an
                        item (or items) is dropped into the Trash (when
                        'PlaySounds=1') - The 'PlaySounds' parameter (see
                        above) specifies whether sounds effects are to be
                        played.

                        DEFAULT:    SystemDefault


   EmptySound=       -  Identifies the FULL path and filename of a Multimedia
                        Wave (.WAV) Audio file that should be played when the
                        Trash is emptied (when 'PlaySounds=1') - The
                        'PlaySounds' parameter (see above) specifies whether
                        sounds effects are to be played.

                        DEFAULT:    SystemDefault
