The purpose of this plugin is to give developers a common "platform/interface" to show PopUps. It is born from the source code of NewStatusNotify, another plugin I've made.
Remember that users *must* have this plugin enabled, or they won't get any popup. Write this in the requirements, do whatever you wish ;-)... but tell them!
NOTE! Since Popup 1.0.1.2 there is a main meun group called "PopUps" where I have put a "Enable/Disable" item.
You can add your own "enable/disable" items by adding these lines before you call MS_CLIST_ADDMAINMENUITEM:
mi.pszPopUpName = Translate("PopUps");
mi.position = 0; //You don't need it and it's better if you put it to zero.
*/
//#define MAX_CONTACTNAME 32
//#define MAX_SECONDLINE 40
#define MAX_CONTACTNAME 2048
#define MAX_SECONDLINE 2048
//This is the basic data you'll need to fill and pass to the service function.
typedef struct {
HANDLE lchContact; //Handle to the contact, can be NULL (main contact).
HICON lchIcon; //Handle to a icon to be shown. Cannot be NULL.
char lpzContactName[MAX_CONTACTNAME]; //This is the contact name or the first line in the plugin. Cannot be NULL.
char lpzText[MAX_SECONDLINE]; //This is the second line text. Users can choose to hide it. Cannot be NULL.
COLORREF colorBack; //COLORREF to be used for the background. Can be NULL, default will be used.
COLORREF colorText; //COLORREF to be used for the text. Can be NULL, default will be used.
WNDPROC PluginWindowProc; //Read below. Can be NULL; default will be used.
void * PluginData; //Read below. Can be NULL.
} POPUPDATA, * LPPOPUPDATA;
typedef struct {
HANDLE lchContact;
HICON lchIcon;
char lpzContactName[MAX_CONTACTNAME];
char lpzText[MAX_SECONDLINE];
COLORREF colorBack;
COLORREF colorText;
WNDPROC PluginWindowProc;
void * PluginData;
int iSeconds; //Custom delay time in seconds. -1 means "forever", 0 means "default time".
char cZero[16]; //16 unused bytes which may come useful in the future.
} POPUPDATAEX, *LPPOPUPDATAEX;
/*
When you call MS_POPUP_ADDPOPUP, my plugin will check if the given POPUPDATA structure is filled with acceptable values. If not, the data will be rejected and no popup will be shown.
- lpzText should be given, because it's really bad if a user chooses to have the second line displayed
and it's empty :-) Just write it and let the user choose if it will be displayed or not.
- PluginWindowProc is a WNDPROC address you have to give me. Why? What? Where? Calm down 8)
My plugin will take care of the creation of the popup, of the destruction of the popup, of the come into
view and the hiding of the popup. Transparency, animations... all this stuff.
My plugin will not (as example) open the MessageWindow when you left click on a popup.
Why? Because I don't know if your popup desires to open the MessageWindow :))))
This means that you need to make a WNDPROC which takes care of the WM_messages you need.
For example, WM_COMMAND or WM_CONTEXTMENU or WM_LMOUSEUP or whatever.
At the end of your WNDPROC remember to "return DefWindowProc(hwnd, msg, wParam, lParam);"
When you process a message that needs a return value (an example could be WM_CTLCOLORSTATIC,
but you don't need to catch it 'cause it's my plugin's job), simply return the nedeed value. :)
The default WNDPROC does nothing.
- PluginData is a pointer to a void, which means a pointer to anything. You can make your own structure
to store the data you need (example: a status information, a date, your name, whatever) and give me a
pointer to that struct.
You will need to destroy that structure and free the memory when the PopUp is going to be destroyed. You'll know this when you receive a UM_FREEPLUGINDATA. The name tells it all: free your own plugin data.
Appendix A: Messages my plugin will handle and your WNDPROC will never see.
WM_CREATE, WM_DESTROY, WM_TIMER, WM_ERASEBKGND
WM_CTLCOLOR* [whatever it may be: WM_CTLCOLORDLG, WM_CTLCOLORSTATIC...]
WM_PAINT, WM_PRINT, WM_PRINTCLIENT
Appendix B: "What do I need to do?!?".
Here is an example in C.
//Your plugin is in /plugins/myPlugin/ or in miranda32/something/
#include "../../plugins/PopUp/m_popup.h"
Define your own plugin data if you need it. In this example, we need it and we'll use NewStatusNotify as example: thsi plugin shows a popup when someone in your contact list changes his/hers status. We'll need to know his status, both current and old one.
wParam = (WPARAM)(HWND)hPopUpWindow (but this is useless, since I'll directly send it to your hPopUpWindow
lParam = 0.
This message is sent to the PopUp when its creation has been finished, so POPUPDATA (and thus your PluginData) is reachable.
Catch it if you needed to catch WM_CREATE or WM_INITDIALOG, which you'll never ever get in your entire popup-life.
Return value: if you process this message, return 0. If you don't process it, return 0. Do whatever you like ;-)
*/
#define UM_INITPOPUP (WM_USER + 0x0202)
/*
wParam = (WPARAM)(HWND)hPopUpWindow
lParam = (LPARAM)(char*)lpzNewText
returns: > 0 for success, -1 for failure, 0 if the failure is due to second line not being shown. (but you could call PUIsSecondLineShown() before changing the text...)
Changes the text displayed in the second line of the popup.
*/
#define MS_POPUP_CHANGETEXT "PopUp/Changetext"
static int __inline PUChangeText(HWND hWndPopUp, LPCTSTR lpzNewText) {
Shows a warning message in a PopUp. It's useful if you need a "MessageBox" like function, but you don't want a modal window (which will interfere with a DialogProcedure. MessageBox steals focus and control, this one not.
wParam = (char*) lpzMessage
lParam = 0;
Returns: 0 if the popup was shown, -1 in case of failure.
*/
#define SM_WARNING 0x01 //Triangle icon.
#define SM_NOTIFY 0x02 //Exclamation mark icon.
#define MS_POPUP_SHOWMESSAGE "PopUp/ShowMessage"
static int __inline PUShowMessage(char* lpzText, BYTE kind) {
