ResUtil - Resources Utility APL+Win Workspace

OVERVIEW

This APL+Win workspace contains useful functions when you need Icons, Bitmaps or Cursors for your application. It will allow you to store them in the Workspace or in a file.

DESCRIPTION

Here is a description of the functions:

ResMake        Given the name of a .BMP, .ICO, .CUR or .ANI file it will read it
               and create a character variable that will be usually smaller then
               the original file on disk. We suggest that the resulting variable
               be saved in the WS with it's corresponding extension like _BMP, _ICO,
               _CUR or _ANI. This is to help you remember what type or resource is
               saved in that variable and it's also necessary for the function
               ResToFile to find the resource variable in the WS.
               *** USAGE for .ICO or .CUR file ***
               resource ← 'System'  ResMake 'your filename' ⍝ System size
               resource ← numbers   ResMake 'your filename' ⍝ size of numbers
               resource ←  empty    ResMake 'your filename' ⍝ same size as file
               *** USAGE for .BMP file ***
               resource ← maskcolor ResMake 'your filename' ⍝ transparent color
               resource ←  empty    ResMake 'your filename' ⍝ regular bitmap
               *** USAGE for .ANI file ***
               The resource will be generated as a strip bitmap with those options:
               resource ← maskcolor ResMake 'your filename' ⍝ transparent color
               resource ←  empty    ResMake 'your filename' ⍝ default background

ResLoad        Given a resource variable made by ResMake, you will obtain an handle
               to be used as ICON, BITMAP or CURSOR resource. If you specify 'Mask'
               as the left argument you will obtain an extra handle that will be
               the mask handle to use when populating your 'Imagelist' using the
               command: ⎕WCALL 'AddImages' handle
               *** USAGE for ICON or CURSOR resource variable ***
               handle ← 'Mask'      ResLoad resource ⍝ Color Bitmap and Mask handles
               handle ← 'Mask Grey' ResLoad resource ⍝ Grey Bitmap and Mask handles
               handle ← 'Grey'      ResLoad resource ⍝ Grey Icon or Cursor
               handle ←  empty      ResLoad resource ⍝ Regular Icon or Cursor handle
               *** USAGE for BITMAP resource variable ***
               handle ← 'Mask'      ResLoad resource ⍝ Color Bitmap and Mask handles
               handle ← 'Mask Grey' ResLoad resource ⍝ Grey Bitmap and Mask handles
               handle ← 'Grey'      ResLoad resource ⍝ Grey Bitmap
               handle ←  color      ResLoad resource ⍝ the Mask is made with that color
               handle ←  empty      ResLoad resource ⍝ Regular Bitmap handle

ResShow        Show the content of a resource variable made by ResMake
               USAGE: ResShow resource

ResSizeOf      To obtain the height and width in pixels of the object in resource
               USAGE: (height width) ← ResSizeOf resource

ResCursor      To change an ICON or BITMAP resource variable to a CURSOR resource
               variable. Used mainly to facilitate the making of colored cursor.
               USAGE: (cusor resource) ← (yhotspot,xhotspot) ResCursor resource

ResDrawBitmap  To Draw a Bitmap resource variable into a picture element. If the
               resource variable has a maskcolor included, the bitmap is drawn
               transparently.
               USAGE: 'your picture name' ResDrawBitmap resource

ResAnimate     To create an Imagelist and a Timer to animate a strip Bitmap.
               The interval is the delay between two frame in 1/1000 of second.
               USAGE:('your picture name' interval) ResAnimate resource

ResToFile      Store all resources variables of the WS into a file. The resource
               variable must end by _ICO, _CUR, _BMP, _ANI or _RES (case insensitive)
               The filename is the name of the APL .sf file (with the DOS path)
               without the .sf extension.
               USAGE: (resource names saved) ← ResToFile filename

ResFromFile    Restore all resources variables into WS from a file saved by ResToFile
               USAGE: (resource names restored) ← ResFromFile filename

ResErase       Erase all resources variables in the WS
               USAGE: ResErase

ResButton      Create a Button with a predefined Glyph. Require the global
               variable Button_Res.
               USAGE: 'parent name' ResButton (id y x action)
                   id: type of button ('OK' 'CANCEL' 'PLUS' 'MINUS' 'HELP')
                  y,x: position of the button
               action: onClick event

PicButton      Create a Button from a predefined Picture. Require the global
               variable PicButton_Res.
               USAGE: 'parent name' PicButton (id y x action)
                   id: type of button ('OK' 'CANCEL' 'PLUS' 'MINUS' 'HELP')
                  y,x: position of the button
               action: onClick event

ResSub         Subroutine to ResMake, ResLoad, ResShow and ResCursor

ResAnimateSub  Subroutine to ResAnimate

EXAMPLES

Here is some examples of what you can do with these functions:

1. If you need an ICON for your title bar:

    logo_ico ← 'System' ResMake 'c:\logo.ico'

    h_logo ← ResLoad logo_ico

    'form name' ⎕wi 'icon' h_logo


2. If you need an ICON for a picture element:

    logo_ico ← 'System' ResMake 'c:\logo.ico'

    h_logo ← ResLoad logo_ico

    'picture name' ⎕wi 'Draw' ('Icon' h_logo)


3. If you need an ICON to populate an Imagelist:

    logo_ico ← 'System' ResMake 'c:\logo.ico'

    h_logo ← 'Mask' ResLoad logo_ico  ⍝ That way you get 2 handles

    'Imagelist name' ⎕wi 'AddImages' h_logo


4. If you need a smaller size ICON (for example an imagelist):

    logo_ico ← 16 16 ResMake 'c:\logo.ico'


5. If you need a cursor for your form:

    wizard_cur ← 'System' ResMake 'c:\wizard.cur'

    h_wizard ← ResLoad wizard_cur

    'form name' ⎕wi 'pointer' ¯1 h_wizard


6. If you need a bitmap for a picture:

    logo_bmp ← ResMake 'c:\logo.bmp'

    h_logo ← ResLoad logo_bmp

    'picture name' ⎕wi 'Draw' ('Bitmap' h_logo)


7. If you need a transparent bitmap for a picture:

    logo_bmp ← 128 128 0 ResMake 'c:\logo.bmp'

    'picture name' ResDrawBitmap logo_bmp


8. If you need a transparent bitmap for an Imagelist:

    logo_bmp ← 128 128 0 ResMake 'c:\logo.bmp'

    h_logo ← 'Mask' ResLoad logo_bmp

   'Imagelist name' ⎕wi 'AddImages' h_logo


9. If you have an .ico file that you want to use as a cursor:

    wizard_ico ← ResMake 'c:\wizard.ico'

    wizard_cur ← 2 8 ResCursor wizard_ico

    h_wizard ← ResLoad wizard_cur


10. If you have a .bmp file that you want to use as a cursor:

    wizard_bmp ← 128 128 0 ResMake 'c:\wizard.bmp'

    wizard_cur ← 2 8 ResCursor wizard_bmp

    h_wizard ← ResLoad wizard_cur


11. If you have an .ani file that you would like to animate on a form:

    globe_ani ← 128 128 0 ResMake 'c:\globe.ani'

    ('picture name' 200) ResAnimate globe_ani

    ⍝ Restriction: the size of an .ani frame must be square


12. If you need to save all the resource variables to an APL file

    ResToFile 'c:\resource'  ⍝ variables must end by _ico, _cur, _bmp, _ani or _res


13. If you need to erase all the resource variables in the WS

    ResErase     ⍝ same restriction as no 12


14. If you need to restore the resource variables saved by ResToFile

    ResFromFile 'c:\resource'


15. If you need GREY Icons or Bitmaps

    h_logo ← 'Mask Grey' ResLoad logo_ico
    h_logo ← 'Grey' ResLoad logo_ico


16. If you need a Bitmap with the Mask Change to a Color
    (usefull when you do animation)

    h ← 'BkColor' 128 0 128 ResLoad 'c:\logo.bmp'



Note 1: When you are populating an Imagelist with 'AddImages' it will accept
        only bitmap handles by definition. It will not work with icon or
        cursor handles.

Note 2: If you are using the 'Mask' option on ResLoad to get a color bitmap
        handle and a mask handle, use ('style' 0) on the Imagelist to signify
        that you want transparency.

Note 3: Use also ('colordepth' 24) on the Imagelist to get all the original colors.

Note 4: Don't try to populate an Imagelist with a regular bitmap handle and
        the option ('maskcolor' 128 128 0) for example. It may or may not work
        depending on the color resolution of your video card. It is always better
        to save the maskcolor at the time of the creation of the bitmap
        resource variable (ie. resource ← maskcolor ResMake filename).

Note 5: Don't forget to delete the handles that you don't need anymore specially
        after you have populated an Imagelist. You can do so by using the function
        Wfree included in this workspace.

Note 6: It's not yet possible to have an animated cursor from an .ani
        resource variable.

Note 7: If you are using an Imagelist with a Mask on a regular Button element with
        no focus ('style' 4), the size of the button must be at least 7 pixels
        larger than the one of the imagelist ('imagesize') or 9 pixels with focus,
        otherwise the mask will still be visible.  On a CommandButton the size of
        the button is adjusted automatically and this phenomena don't exist.

VERSION

March 2002      - First Release of WS

May 2002        - The 'ResLoad' function was modified to accept the word 'Grey'
                  as a new option. When used the icon or bitmap handles will be
                  generated with 256 shades of grey instead of color. The 'Mask'
                  option can be used at the same time.

                - The following expression: handle←⌊(¯2*31)+(2*32)|(2*31)+handle
                  was added in ResLoad and ResSub to coerce a floating point
                  number handle to an integer number handle. APL is expecting an
                  integer number handle when populating a 'Toolbar' with the
                  'list' property.

                - ⌊ was missing in ResSub for DECODE 12, 7, 6, 5 and 3. ResLoad
                  was not able to create an handle under certain conditions.

                - It's now possible to enter a Background color when using ResLoad.
                  The handle will have the mask of the Bitmap change for that
                  color when created. Usefull when doing animation.

March 2007      - Bug Fix when loading a resource with a mask, not a multiple
                  of 16 pixels wide.

                - Fix to work with evolution level 1.

December 2008   - Bug Fix with large bitmap.

                - ⎕WCALL 'ReadFile' has 5 arguments now instead of 4.

February 2009   - Bug Fix with large bitmap

DOWNLOAD

The workspace in APL+Win version 5 can be downloaded here: ResUtil.w3

INFORMATION

Original author:

Pierre Gilbert

Responsible:

PierreGilbert

Email:

<apgil AT SPAMFREE videotron DOT ca>


CategoryApl2000

apwResUtil (last edited 2015-04-04 11:57:58 by PierreGilbert)