Documentation for Win32lib v0.60.6
Table of Contents

MouseTraps

Defined sub-regions of a window that can generate w32HMouseTrap events.


These are used to make it easy to detect mouse activity in specific sub-regions of a window or other control.

  • func createMouseTrap(integer pWindow, object pRect)   Defines a mousetrap area
  • proc deleteMouseTrap(integer pWindow, integer pMouseTrap)   This removes the specified mousetrap area from the window.
  • proc enableMouseTrap(integer pWindow, object pMouseTrap, integer pState)   This alters the 'enabled' state of the specified mousetrap area in the window.
  • proc filterMouseTrap(integer pWindow, object pMouseTrap, object pEvents)   This alters the 'filters' of the specified mousetrap area in the window.
  • func getMouseTrap(integer pWindow, object pMouseTrap)   This fetches all the information about the specified mousetrap.
  • func getTagMouseTrap(integer pWindow, object pMouseTrap)    This fetches the data stored by setTagMouseTrap()
  • func hitMouseTrap(integer pWindow, integer pEvent, integer pX, integer pY)    This returns all mousetraps for the window that are under the pX and pY position.
  • proc setTagMouseTrap(integer pWindow, object pMouseTrap, object pData)   This alters the 'user data' of the specified mousetrap area in the window.
  • proc updateMouseTrap(integer pWindow, integer pMouseTrap, object pRect)   This changes the bounding rectangle for a mousetrap.
  • proc zorderMouseTrap(integer pWindow, object pMouseTrap, integer pOrder)   This alters the 'depth' of the specified mousetrap area in the window.

    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    createMouseTrap
    (integer pWindow, object pRect)

    Defines a mousetrap area

    Returns: INTEGER: A mousetrap ID.

    Category: MouseTraps

    This defines an subregion of pWindow, bounded by pRect that can generate w32HMouseTrap events.
    pWindow is a top-level Window control. It must not have any parent.
    pRect is either a four-element sequence in the form
    {left, top, right, bottom} relative to pWindow, or the id of a child control of pWindow. In the second case, the mousetrap covers the entire area of the child control.

    Example:

          integer mt
          mt1 = createMouseTrap(myWin, {10,10,30,30})
          mt2 = createMouseTrap(myWin, myBitMap)
    

    See Also: deleteMouseTrap, enableMouseTrap, filterMouseTrap, getMouseTrap, getTagMouseTrap, hitMouseTrap, setTagMouseTrap, updateMouseTrap, zorderMouseTrap


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    deleteMouseTrap
    (integer pWindow, integer pMouseTrap)

    This removes the specified mousetrap area from the window.

    Category: MouseTraps

    pWindow is the window that owns the mousetrap.
    pMouseTrap is the id of the mouse trap to remove.

    Note that if pMouseTrap is less than one, all mousetraps for the window will be deleted.

    Example:

          -- Remove mousetrap #3
          deleteMouseTrap(MyWindow, 3)
          -- Remove all mousetraps from the window.
          deleteMouseTrap(DiagWin, -1)
    
    -------------------------------------------------------

    See Also: createMouseTrap, enableMouseTrap, filterMouseTrap, getMouseTrap, getTagMouseTrap, hitMouseTrap, setTagMouseTrap, updateMouseTrap, zorderMouseTrap


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    enableMouseTrap
    (integer pWindow, object pMouseTrap, integer pState)

    This alters the 'enabled' state of the specified mousetrap area in the window.

    Category: MouseTraps

    pWindow is the window that owns the mousetrap.
    pMouseTrap is the id of the mouse trap to enable.
    pState is either w32True or w32False. A setting of w32False will prevent this mousetrap from generating events.

    Note that pMouseTrap can also be a list of mousetrap Ids.

    Example:

          -- Disable mousetrap #1
          enableMouseTrap(myWin, 1, w32False)
          -- Enable mousetraps #2, 8, 5, and 4.
          enableMouseTrap(myWin, {2,8,5,4}, w32True)
    
    -------------------------------------------------------

    See Also: createMouseTrap, deleteMouseTrap, filterMouseTrap, getMouseTrap, getTagMouseTrap, hitMouseTrap, setTagMouseTrap, updateMouseTrap, zorderMouseTrap


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    filterMouseTrap
    (integer pWindow, object pMouseTrap, object pEvents)

    This alters the 'filters' of the specified mousetrap area in the window.

    Category: MouseTraps

    pWindow is the window that owns the mousetrap.
    pMouseTrap is the id of the mouse trap to filter.
    pEvents is a list of Windows mouse event codes. These are the only mouse events that can cause this mousetrap area to react.

    Note that pMouseTrap can also be a list of mousetrap Ids.

    Example:

          -- Check for Wheel movement
          filterMouseTrap(myWin, 1, WM_WHEELMOUSE)
          -- Check for Right Button events
          filterMouseTrap(myWin, {2,8,5,4}, {WM_RBUTTONDOWN, WM_RBUTTONUP})
    
    -------------------------------------------------------

    See Also: createMouseTrap, deleteMouseTrap, enableMouseTrap, getMouseTrap, getTagMouseTrap, hitMouseTrap, setTagMouseTrap, updateMouseTrap, zorderMouseTrap


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    getMouseTrap
    (integer pWindow, object pMouseTrap)

    This fetches all the information about the specified mousetrap.

    Returns: OBJECT: -1 if pMouseTrap is not valid, otherwise a MouseTrap sequence.

    Category: MouseTraps

    pWindow is the window that owns the mousetrap.
    pMouseTrap is the id of the mouse trap.

    Each mousetrap is a sequence of 8 elements:

  • integer: zorder, the higher numbers are further in the background. The initial value is zero when a mousetrap is created.
  • integer: left, the leftmost position of the mousetrap area
  • integer: top, the topmost position of the mousetrap area
  • integer: right, the rightmost position of the mousetrap area
  • integer: bottom, the bottommost position of the mousetrap area
  • integer: enableFlag, either w32True if enabled else w32False.
  • object: userdata, the data set by calling setTagMouseTrap(). This is never used by win32lib and is intended for use by the user for anything.
  • sequence: filters, a list of zero or more mouse event codes that are used to filter in this mousetrap. Initially this set to {WM_LBUTTONDOWN} when then mousetrap is created. It can be changed by calling filterMouseTrap().

    Example:

          -- Fetch the mousetrap info.
          object MT
          MT = getMouseTrap(MyWindow, 1)
          if atom(MT) then
              -- the mousetrap doesn't exist.
          else
              -- process it...
          end if
    
    -------------------------------------------------------

    See Also: createMouseTrap, deleteMouseTrap, enableMouseTrap, filterMouseTrap, getTagMouseTrap, hitMouseTrap, setTagMouseTrap, updateMouseTrap, zorderMouseTrap


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    getTagMouseTrap
    (integer pWindow, object pMouseTrap)

    This fetches the data stored by setTagMouseTrap()

    Returns: OBJECT: Whatever the user data has been set for the mousetrap.

    Category: MouseTraps

    pWindow is the window that owns the mousetrap.
    pMouseTrap is the id of the mouse trap that holds the data.

    You must use setTagMouseTrap() to store this data.

    Example:

          -- Save a routine id to handle things.
          setTagMouseTrap(MyWindow, 1, routine_id("MT1_Catch"))
          . . .
          -- Fetch the routine id to use.
          rtnid = getTagMouseTrap(MyWindow, 1)
          call_proc(rtnid, . . .)
    

    -------------------------------------------------------

    See Also: createMouseTrap, deleteMouseTrap, enableMouseTrap, filterMouseTrap, getMouseTrap, hitMouseTrap, setTagMouseTrap, updateMouseTrap, zorderMouseTrap


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    hitMouseTrap
    (integer pWindow, integer pEvent, integer pX, integer pY)

    This returns all mousetraps for the window that are under the pX and pY position.

    Returns: SEQUENCE: A list of zero or more mousetraps.

    Category: MouseTraps

    pWindow is the window that owns the mousetrap.
    pEvent used to filter. Only mousetraps looking for this event can be returned./n pX, pY are coordinates. Only mousetraps that are under this position can be returned.

    Note that disabled mousetraps are ignored.

    The returned list is sorted from closest to furtherest away, based on the z-order settings of the mousetraps. These are set by calling zorderMouseTrap().

    The format of each element in the returned list is :

  • integer: zorder
  • integer: left
  • integer: top
  • integer: right
  • integer: bottom
  • integer: mousetrap id
  • object: userdata
  • sequence: filters

    Example:

          sequence MTList
          -- Get all the mousetraps that are under (100,100) that are looking for
          -- left button down events.
          MTList = hitMouseTrap(myWindow, WM_LBUTTONDOWN, 100, 100)
    

    -------------------------------------------------------

    See Also: createMouseTrap, deleteMouseTrap, enableMouseTrap, filterMouseTrap, getMouseTrap, getTagMouseTrap, setTagMouseTrap, updateMouseTrap, zorderMouseTrap


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    setTagMouseTrap
    (integer pWindow, object pMouseTrap, object pData)

    This alters the 'user data' of the specified mousetrap area in the window.

    Category: MouseTraps

    pWindow is the window that owns the mousetrap.
    pMouseTrap is the id of the mouse trap to hold the data.
    pData is any data you wish to store with this mousetrap.

    Win32lib never uses this data. It is a convenience for the coder to save data specific for the user-defined mousetrap event processing.

    You can use getTagMouseTrap() to retrieve this data.

    Example:

          -- Save a routine id to handle things.
          setTagMouseTrap(MyWindow, 1, routine_id("MT1_Catch"))
    

    -- Save some color data setTagMouseTrap(MyWindow, 2, {Red, Cyan, BrightGreen})

    -------------------------------------------------------

    See Also: createMouseTrap, deleteMouseTrap, enableMouseTrap, filterMouseTrap, getMouseTrap, getTagMouseTrap, hitMouseTrap, updateMouseTrap, zorderMouseTrap


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    updateMouseTrap
    (integer pWindow, integer pMouseTrap, object pRect)

    This changes the bounding rectangle for a mousetrap.

    Category: MouseTraps

    pWindow is the window that owns the mousetrap.
    pMouseTrap is the id of the mouse trap to update.
    pRect is either a four-element sequence in the form
    {left, top, right, bottom} relative to the pWindow control, or the id of a child control of pWindow. In the second case, the mousetrap covers the entire area of the child control.

    Note that if the specified mousetrap does not exist, it will be created automatically.

    Example:

          updateMouseTrap(myWin, 2, {20,17,156, 281})
          updateMouseTrap(myWin, 1, myBitMap)
    
    -------------------------------------------------------

    See Also: createMouseTrap, deleteMouseTrap, enableMouseTrap, filterMouseTrap, getMouseTrap, getTagMouseTrap, hitMouseTrap, setTagMouseTrap, zorderMouseTrap


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    zorderMouseTrap
    (integer pWindow, object pMouseTrap, integer pOrder)

    This alters the 'depth' of the specified mousetrap area in the window.

    Category: MouseTraps

    pWindow is the window that owns the mousetrap.
    pMouseTrap is the id of the mouse trap to order.
    pOrder the absolute depth value. The higher the number, the further in the background the mousetrap area is. Initially a mousetrap is created with a depth value of zero. Negative numbers move the mousetrap closer to the foreground.

    Use this if you have mousetrap areas that can overlap. When the w32HMouseTrap event fires, you get a list of mousetrap areas sorted from closest (in foreground) to furtherest (in background).

    Example:

          -- move area #1 close to the front.
          zorderMouseTrap(MyWindow, 1, -10)
    

    -- Order things so that the man is in front of the -- bush and the bush is in front of the wall. zorderMouseTrap(MyWindow, Wall, 3) zorderMouseTrap(MyWindow, Bush, 2) zorderMouseTrap(MyWindow, Man, 1)

    -------------------------------------------------------

    See Also: createMouseTrap, deleteMouseTrap, enableMouseTrap, filterMouseTrap, getMouseTrap, getTagMouseTrap, hitMouseTrap, setTagMouseTrap, updateMouseTrap