In This Topic ▼

L_StartMagGlass

Summary

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

Syntax

#include "l_bitmap.h"

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

Parameters

L_HWND hWnd

Handle of the window to which to attach the Magnifying Glass.

pBITMAPHANDLE pBitmap

Pointer to the bitmap handle that references the bitmap displayed in hWnd.

L_RECT * prcDst

Pointer to the display destination rectangle.

MAGGLASSOPTIONS * pMagGlassOptions

Pointer to a MAGGLASSOPTIONS structure which contains the options for controlling the behavior of the Magnifying Glass.

MAGGLASSCALLBACK 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.

L_VOID* 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

Value	Meaning
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.

Notes:

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.
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

Win32, x64.

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, 
   L_RECT*           prcView, 
   L_BOOL            bConnected, 
   pMAGGLASSOPTIONS  MagGlassOpt, 
   L_INT             gMaskCount, 
   L_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 = (L_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 */ 
 
extern "C" L_INT EXT_CALLBACK MagGlassCallback(L_HWND hWnd, 
   L_INT    nMaskPlaneStart, 
   L_INT    nMaskPlaneEnd, 
   L_UCHAR* pMaskPlane, 
   L_INT    nMaskPlaneSize, 
   L_VOID*  pUserData) 
{ 
   L_COLORREF* pColor = (L_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; 
} 
 
extern "C" L_INT StartMagGlassFirstExample(L_HWND hWnd, 
   L_RECT*           prcView, 
   pMAGGLASSOPTIONS  MagGlassOpt, 
   pBITMAPHANDLE     pBitmap, 
   L_BOOL*           bMagGlass) 
{ 
   L_INT nRet; 
   L_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 = (L_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) 
      { 
         _tprintf(_T("%s"), TEXT("Error Starting MagGlass!")); 
         return nRet; 
      } 
      else 
         *bMagGlass = TRUE; 
   } 
 
   return SUCCESS; 
} 
 
extern "C" L_VOID StopMagGlass(L_HWND hWnd, L_BOOL * bMagGlass) 
{ 
   if (*bMagGlass) 
   { 
      L_StopMagGlass(hWnd); 
 
      *bMagGlass = FALSE; 
   } 
}