L_StartMagGlass

#include "l_bitmap.h"

L_LTDIS_API L_INT L_StartMagGlass(hWnd, pBitmap, prcDst, pMagGlassOptions, pfnCallback, pUserData)

L_HWND hWnd;	/* handle to a window */
pBITMAPHANDLE pBitmap;	/* pointer to the bitmap handle */
L_RECT * prcDst;	/* pointer to the display destination rectangle */
MAGGLASSOPTIONS * pMagGlassOptions;	/* pointer to MagGlass options structure */
MAGGLASSCALLBACK pfnCallback;	/* optional callback function */
L_VOID* pUserData;	/* pointer to more parameters for the callback */

Starts the Magnify Glass procedure by attaching a magnifying glass to the specified window.

Parameter	Description
hWnd	Handle of the window to which to attach the Magnifying Glass.
pBitmap	Pointer to the bitmap handle that references the bitmap displayed in hWnd.
prcDst	Pointer to the display destination rectangle.
pMagGlassOptions	Pointer to a MAGGLASSOPTIONS structure which contains the options for controlling the behaviour of the Magnifying Glass.
pfnCallback	Optional callback function for additional processing.
	If you do not provide a callback function, use NULL as the value of this parameter.
	If you do provide a callback function, use the function pointer as the value of this parameter.
	The callback function must adhere to the function prototype described in MAGGLASSCALLBACK function.
pUserData	Void pointer that you can use to pass one or more additional parameters that the callback function needs.
	To use this feature, assign a value to a variable or create a structure that contains as many fields as you need. Then, in this parameter, pass the address of the variable or structure, casting it to L_VOID *. The callback function, which receives the address in its own pUserData parameter, can cast it to a pointer of the appropriate data type to access your variable or structure.
	If the additional parameters are not needed, you can pass NULL in this parameter.

Returns

SUCCESS	The function was successful.
< 1	An error occurred. Refer to Return Codes.

Comments

After calling this function, LEADTOOLS will monitor the window's messages, looking for mouse messages, and processing them by displaying a "Magnifying Glass" if and only if the MAGGLASS_MANUAL_UPDATE flag was not set.

If a callback function is passed to this function, information about the non-updated parts of the bitmap can be obtained from the callback function. This callback function receives information when the left mouse button is pressed or released and when the mouse is moved while the left mouse button is pressed. This information can be used to determine when to call L_UpdateMagGlass.

If a callback function is passed to this function, L_UpdateMagGlass must be called in order to paint the zoomed image in the Magnifying Glass display area.

If the MAGGLASS_MANUAL_UPDATE flag was set, LEADTOOLS will not handle the mouse events to manipulate the magnifying glass, so its the users responsibility to add the needed code to manipulate the magnifying glass. L_ShowMagGlass, L_SetMagGlassPos and L_UpdateMagGlassBitmap functions can be used in this case. For example: L_ShowMagGlass can be used with bShow set to TRUE to display the Magnifying glass when the mouse is pressed in the window to which the magnifying glass is attached. In addition, the L_SetMagGlassPos function can be called with the current cursor position when the mouse moves over the magnifying glass window.

Note:	Anytime the window's size changes or the bitmap changes, you should stop the Magnifying Glass procedure and re-start it, in order to update the settings.
Note:	Do not stop the Magnifying Glass procedure in response to scroll messages (WM_VSCROLL and WM_HSCROLL). Instead, call L_UpdateMagGlassRect to update the destination rectangle.

The appearance of the magnifying glass depends on the values of bEllipse, clrPen, b3D and nBorderSize. This can be seen in the table below:

Bellipse	b3D	nBorderSize	clrPen	Result
TRUE	Ignored	valid	valid	An elliptical magnifying glass of border size nBorderSize and border color clrPen.
FALSE	FALSE	valid	valid	A rectangular magnifying glass with a flat border of width nBorderSize and border color clrPen.
FALSE	TRUE	ignored	ignored	A rectangular magnifying glass with a 3D border having a set width and color.

Note:

To make use of other shapes of the Magnifying Glass use L_UpdateMagGlassShape function.

Required DLLs and Libraries

LTDIS

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

Platforms

Windows 2000 / XP/Vista, Windows CE.

See Also

Example

This sample checks to see if the Magnifying Glass was already started using the global bConnected, and if it has, restarts the process. This would be used in WM_SIZE or WM_xSCROLL to update the Magnifying Glass after a change to the destination rect, rcView.

L_INT  StartMagGlassSecondExample(L_HWND             hWnd,
                                                 pBITMAPHANDLE    pBitmap,
                                                 RECT*            prcView,
                                                 L_BOOL           bConnected,
                                                 pMAGGLASSOPTIONS MagGlassOpt,
                                                 L_INT            gMaskCount,
                                                 COLORREF         gMask[])
{
   L_INT nRet;
   if(bConnected)
      L_StopMagGlass(hWnd);

   memset(MagGlassOpt, 0, sizeof(MAGGLASSOPTIONS));
   MagGlassOpt->uStructSize = sizeof (MAGGLASSOPTIONS);

   MagGlassOpt->nWidth         = 100;
   MagGlassOpt->nHeight        = 100;
   MagGlassOpt->nZoom          = 400;
   MagGlassOpt->clrPen         = RGB(0,0,0);
   MagGlassOpt->hMagCursor     = NULL;
   MagGlassOpt->clrBack        = RGB(128,128,128);
   MagGlassOpt->bEllipse       = FALSE;
   MagGlassOpt->nBorderSize    = 1;
   MagGlassOpt->b3D            = FALSE;
   MagGlassOpt->uPaintFlags    = 0;
   MagGlassOpt->pMask          = (COLORREF*)&gMask;
   MagGlassOpt->uMaskCount     = gMaskCount;
   MagGlassOpt->uMagGlassFlags = MAGGLASS_MASK_NORMAL;
   MagGlassOpt->nCrosshair     = CROSSHAIR_FINE;
   MagGlassOpt->bIgnoreRgn     = TRUE;
   MagGlassOpt->bCenter        = TRUE;

   nRet = L_StartMagGlass (hWnd,
                    pBitmap,
                    prcView,
                    MagGlassOpt,
                    NULL,
                    (L_VOID *)gMask);
   if(nRet != SUCCESS)
      return nRet;
   bConnected = L_WindowHasMagGlass(hWnd);
   return SUCCESS;
}

/*
   This sample shows how you can start and stop the Magnifying Glass. It also
   shows the ability to provide a callback function and how this can help you 
   provide the Magnifying Glass with a color buffer to update parts of the bitmap
   as soon as the left button is
   pressed and the mouse moves on the window.
*/


/* assume that pColor is filled with the pixel colors of the non-updated parts of the bitmap when you use the LEADTOOLS Internet functions */

L_INT EXT_CALLBACK MagGlassCallback (L_HWND       hWnd,
                                     L_INT      nMaskPlaneStart,
                                     L_INT      nMaskPlaneEnd,
                                     L_UCHAR*   pMaskPlane,
                                     L_INT      nMaskPlaneSize,
                                     L_VOID*    pUserData)
{
   COLORREF * pColor  = (COLORREF *)pUserData; 
   UNREFERENCED_PARAMETER(nMaskPlaneSize);
   L_INT nRet;
//...
//... send LEADTOOLS Internet command to fill the pColor array.
//...
   nRet = L_UpdateMagGlass (hWnd, pColor, pMaskPlane, nMaskPlaneStart, nMaskPlaneEnd, TRUE);
   return nRet;
}

 L_INT StartMagGlassFirstExample(L_HWND hWnd, 
                                                RECT *prcView,
                                                pMAGGLASSOPTIONS   MagGlassOpt,
                                                pBITMAPHANDLE     pBitmap,
                                                L_BOOL *bMagGlass)
{
   L_INT nRet;
   COLORREF Mask[] = {RGB(255,255,255), RGB(255, 0, 0), RGB(255,64,255), RGB(0,0,255), RGB(255,255,0), RGB(0,255,0)};

   if(! *bMagGlass)
   {
      memset(MagGlassOpt, 0, sizeof(MAGGLASSOPTIONS));
      MagGlassOpt->uStructSize    = sizeof (MAGGLASSOPTIONS);
      MagGlassOpt->nWidth         = 100;
      MagGlassOpt->nHeight        = 100;
      MagGlassOpt->nZoom          = 400;
      MagGlassOpt->clrPen         = RGB(0,0,0);
      MagGlassOpt->hMagCursor     = NULL;
      MagGlassOpt->clrBack        = RGB(128,128,128);
      MagGlassOpt->bEllipse       = FALSE;
      MagGlassOpt->nBorderSize    = 1;
      MagGlassOpt->b3D            = FALSE;
      MagGlassOpt->uPaintFlags    = 0;
      MagGlassOpt->pMask          = (COLORREF*)&Mask;
      MagGlassOpt->uMaskCount     = 6;
      MagGlassOpt->uMagGlassFlags = MAGGLASS_MASK_NORMAL;
      MagGlassOpt->nCrosshair     = CROSSHAIR_FINE;
      MagGlassOpt->bIgnoreRgn     = TRUE;
      MagGlassOpt->bCenter        = TRUE;

      nRet = L_StartMagGlass(hWnd,
                             pBitmap,
                             prcView,
                             MagGlassOpt,
                             (MAGGLASSCALLBACK) (MagGlassCallback),
                             NULL);

      if(nRet!=SUCCESS)
      {
         MessageBox(hWnd, TEXT("Error Starting MagGlass!"), TEXT("Error"), MB_OK);
         return nRet;
      }
      else
         *bMagGlass = TRUE;
   }
   return SUCCESS; 
}

L_VOID StopMagGlass(L_HWND hWnd,L_BOOL *bMagGlass)
{
   if(*bMagGlass)
   {
      L_StopMagGlass(hWnd);

      *bMagGlass = FALSE;
   }
}

Functions:	L_StartMagGlass, L_StopMagGlass, L_UpdateMagGlassShape, L_UpdateMagGlass, MAGGLASSCALLBACK, L_SetMagGlassPaintOptions, L_ShowMagGlass, L_SetMagGlassPos, L_UpdateMagGlassBitmap, L_CreateZoomView, L_GetZoomViewProps, L_UpdateZoomView, L_DestroyZoomView, L_GetZoomViewsCount, L_WindowHasZoomView, ZOOMVIEWPROPS
Topics:	Using the Magnifying Glass
	Raster Image Functions: Displaying Images
	Using Color Values in LEADTOOLS
	Using the Zoom View