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(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;
}
}