home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / shapewin.zip / shapewin.txt < prev    next >
Text File  |  1999-02-02  |  9KB  |  225 lines
  1.  
  2.                 ShapeWin - non-rectangular window support
  3.  
  4.         Copyright (C) 1998, 1999 Software Research Associates, Inc.
  5.  
  6.                     akira@sra.co.jp
  7.  
  8. 1. Introduction
  9.  
  10.     It is bit hard for OS/2 PM to display images on desktop without 
  11.     window rectangle.
  12.  
  13.         Once, I tried such program and failed.  Copying some area of
  14.         desktop and write images over it, it seems as drawing desktop
  15.         direct, but if background was changed, unmatched background
  16.         appears.
  17.  
  18.     Then, I read Shape Extension code of X server, and astonished at its
  19.     simple implementation, and thought it may be implemented on PM. 
  20.     Now, I implemented shape extension look-alike on PM, and release to
  21.     public.
  22.  
  23. 2. Creating Shape Window
  24.  
  25. 2.1. Registering Window Class
  26.  
  27.     Shape Window was implemented as custom control (widget). To use it,
  28.     you need to register window class with 'WinRegisterClass'.
  29.     
  30.         WinRegisterClass(
  31.         hab,                Anchor Block Handle
  32.         ShapeWinName,       Class Name
  33.         ShapeWinProc,       Window Procedure
  34.         0L,                 Default Window Style
  35.         sizeof(PVOID)) ;    Class Data Size
  36.         
  37.     Class name and window procedure is defined in 'shapewin.h'.  But
  38.     class name may be another name.  Class data size should be above
  39.     size.
  40.  
  41. 2.2. Create Shape Window
  42.  
  43.     You can create Shape Window with 'WinCreateWindow' as normal windows.
  44.     But you should note followings.
  45.  
  46.     o To display shape (non-rectangular) window on your desktop, parent
  47.       window should be DESKTOP.  Otherwise, shape window will displayed
  48.       in another normal (rectanglar) window.
  49.  
  50.     o For normal PM programs, top level window is frame window (or sub-
  51.       classed frame window).  Shape window itself don't have function
  52.       corresponds to frame window.  So using shape window as top level
  53.       window is danger.
  54.  
  55.     o According to above two, you should use frame window as top level
  56.       window, and create shape window with frame window as owner window.
  57.       But in this method, you should sub-class frame window and append
  58.       some message processing (described later).
  59.  
  60.     o Control Data is required to create shape window (cannot omit). 
  61.       Detail of control data will describe later.
  62.  
  63.     o Size of shape window is defined by control data and you cannot
  64.       change it size later.  Also, size parameters in WinCreateWindow
  65.       is ignored.
  66.  
  67. 2.3. Shape Control Data
  68.  
  69.     Size, shape and contents of shape window is defined with control
  70.     data.
  71.  
  72.         You can change contents of shape window after, but you cannot
  73.     change shape and size of shape window.
  74.  
  75.     Control data for shape window is defined below (shapewin.h).
  76.     
  77.     typedef struct _SHAPEWIN {
  78.         SHORT   cx, cy  ;       Size of Shape
  79.         HPS     hpsMask ;       Mask Pattern (as Shape)
  80.         HPS     hpsDraw ;       Source of Drawing Data
  81.     } SHAPEWIN, *PSHAPEWIN ;
  82.  
  83.     cx * cy image in a presentation space 'hpsMask' determines shape of
  84.     shape window (as mask pattern).  And image in a presentation space 
  85.     'hpsDraw' will  written to shape window (drawing data).
  86.  
  87. 2.4. Mask Pattern
  88.  
  89.     Shape window uses image in 'hpsMask' as mask pattern.  It assumes
  90.     color at pixel (0, 0) as background color, and area of another color
  91.     as shape of drawing area.
  92.     
  93.     Usually, fill memory PS with background color and draw any image
  94.     over it.  If background color is not in drawing area, you may use
  95.     same memory PS as both mask pattern and drawing data.
  96.  
  97.         Samples programs all uses this method.
  98.     
  99.     There is no limit for size of mask pattern.  But using large image,
  100.     or complicated image eat up lot CPU.
  101.     
  102. 2.5. Update Drawing Data
  103.  
  104.     Via presentaion space 'hpsDraw', you can update contents of shape
  105.     window.
  106.  
  107.     You can draw anything on presetation space 'hpsDraw'. To update
  108.     new images on 'hpsDraw' to shape window, send following message to
  109.     shape window.
  110.  
  111.     SHAPEWIN_MSG_UPDATE     Request to update window contents
  112.     
  113.         param1          PRECTL      update region
  114.     param2          NULL
  115.  
  116.     Only a part of 'hpsDraw' was changed, and want to avoid unneccesary
  117.     drawing, specify update region to restrict window updates. Update
  118.     region may NULL, in this case, shape window redraw entire area.
  119.     Redraw on shape window is quite a heavy processing, your should
  120.     specify update region.
  121.  
  122.         But if your CPU & Video board fast enough, redrawing entire
  123.         region  may be faster.
  124.  
  125. 3. Combination with Frame Window
  126.     
  127.     Contents of this section is so called 'VooDoo'.  Following methods
  128.     works for my environment (Warp3/Connect), but I am not sure they
  129.     works other environments.  If these methods bot worked on your
  130.     environments, or if you know more good methods, let me know.
  131.  
  132.     If you use shape window, you want to draw some images on desktop
  133.     direct (not in another window).  For this, you should create shape
  134.     window as child of desktop window.  But shape window does not have
  135.     frame functions, use shape window as top level window is dangerous.
  136.     So you should create shape window with
  137.  
  138.         Parent Window       DESKTOP (HWND_DESKTOP)
  139.         Owner Window        frame window
  140.     
  141.     If you create frame & shape window as above, there is no parent/
  142.     child releation between frame and shape.  In this case, some
  143.     controls usually worked between frame and client does not works.
  144.     To enable such controls, you should customize (sub-class) frame
  145.     window processing.
  146.     
  147.     Also, if you create frame & shape as above, both frame and shape
  148.     window appear on desktop.  To hide frame window (to use non-
  149.     rectangular drawing are on desktop), you should customize frame
  150.     window, too.
  151.  
  152. 3.1. Relay Frame Control Messages
  153.  
  154.     If size, position, or Z-order of frame window was changed, following
  155.     frame window procedure receives following messages.
  156.     
  157.         WM_ADJUSTWINDOWPOS      before change
  158.     WM_WINDOWPOSCHANGED     after  change
  159.  
  160.     To follow shape window's position, Z-order to frame window, hook
  161.     these messages and control shape window's position / Z-order, such
  162.     as
  163.  
  164.         case WM_ADJUSTWINDOWPOS :
  165.         pswp = (PSWP) PVOIDFROMMP(mp1) ;
  166.         WinSetWindowPos(hwndShape, pswp->hwndInsetBehind,
  167.                 pswp->x, pswp->y, pswp->cx, pswp->cy, pswp->fl) ;
  168.             return defaultFrameProc(...) ;
  169.  
  170.     or
  171.     
  172.         case WM_WINDOWPOSCHANGED :
  173.         pswp = (PSWP) PVOIDFROMMP(mp1) ;
  174.         WinSetWindowPos(hwndShape, pswp->hwndInsetBehind,
  175.                 pswp->x, pswp->y, pswp->cx, pswp->cy, pswp->fl) ;
  176.             return defaultFrameProc(...) ;
  177.  
  178.     But WM_WINDOWPOSCHANGED will never happen if you make frame window
  179.     invisible (describe in next section).
  180.  
  181.     See sample codes for more deatils.
  182.  
  183. 3.2. Invisible Frame Window
  184.  
  185.     Create frame and shape window, but not to show frame window, you can
  186.     make frame window invisible.
  187.     
  188.     To do this, hook 'WM_ADJUSTWINDOWPOS' message and modify SWP data.
  189.  
  190.         case WM_ADJUSTWINDOWPOS :
  191.         pswp = (PSWP) PVOIDFROMMP(mp1) ;
  192.         WinSetWindowPos(hwndShape, pswp->hwndInsetBehind,
  193.                 pswp->x, pswp->y, pswp->cx, pswp->cy, pswp->fl) ;
  194.             pswp->fl &= ~SWP_SHOW ;
  195.             return defaultFrameProc(...) ;
  196.  
  197.     Also you can make frame window to fixed size as
  198.  
  199.         case WM_ADJUSTWINDOWPOS :
  200.         pswp = (PSWP) PVOIDFROMMP(mp1) ;
  201.         WinSetWindowPos(hwndShape, pswp->hwndInsetBehind,
  202.                 pswp->x, pswp->y, pswp->cx, pswp->cy, pswp->fl) ;
  203.             pswp->cx = fixed_width  ;
  204.             pswp->cy = fixed_height ;
  205.             pswp->fl &= ~SWP_SHOW ;
  206.             return defaultFrameProc(...) ;
  207.  
  208.     See sample codes (trbitmap.c, tranime.c) for more deatils.
  209.  
  210. 3.3. Notify Key & Mouse Events
  211.  
  212.     Key and mouse events in shape window will send to it's owner (frame
  213.     window).  So if you want to control on such event, you should
  214.     implement such code on (customized) frame window procedure.
  215.  
  216.     For mouse related messages, mouse position is set in their parameter.
  217.     But if they are transferred from shape window, those positions are
  218.     relative to small windows wich contruct shape window itself, and not
  219.     adjusted to frame window relative.
  220.  
  221.     If you need mouse positions, use 'WinQueryPointerPos' to acquire
  222.     correct mouse locations.
  223.  
  224.     See sample codes (trbitmap.c, treyes.c) for more details.
  225.