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

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

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(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 (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(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(HWND hWnd,L_BOOL *bMagGlass)
{
   if(*bMagGlass)
   {
      L_StopMagGlass(hWnd);
      *bMagGlass = FALSE;
   }
}