home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / MISC / LSW270SR.ZIP / widget / xwph / center.h next >
Text File  |  2002-08-10  |  62KB  |  1,450 lines
  1.  
  2. /*
  3.  *@@sourcefile center.h:
  4.  *      public header file for the XCenter and plugins.
  5.  *
  6.  *      This contains all declarations which are needed by
  7.  *      all parts of the XCenter and to implement widget
  8.  *      plugin DLLs.
  9.  *
  10.  *      WARNING: The XCenter is still work in progress. The
  11.  *      definitions in this file are still subject to change,
  12.  *      even though I try to maintain backwards compatibility.
  13.  *
  14.  *      If you are looking at this file from the "toolkit\shared"
  15.  *      directory of a binary XWorkplace release, this is an
  16.  *      exact copy of the file in "include\shared" from the
  17.  *      XWorkplace sources.
  18.  *
  19.  *@@include #include "shared\center.h"
  20.  */
  21.  
  22. /*
  23.  *      Copyright (C) 2000-2002 Ulrich Möller.
  24.  *      This file is part of the XWorkplace source package.
  25.  *      XWorkplace is free software; you can redistribute it and/or modify
  26.  *      it under the terms of the GNU General Public License as published
  27.  *      by the Free Software Foundation, in version 2 as it comes in the
  28.  *      "COPYING" file of the XWorkplace main distribution.
  29.  *      This program is distributed in the hope that it will be useful,
  30.  *      but WITHOUT ANY WARRANTY; without even the implied warranty of
  31.  *      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  32.  *      GNU General Public License for more details.
  33.  */
  34.  
  35. #ifndef CENTER_HEADER_INCLUDED
  36.     #define CENTER_HEADER_INCLUDED
  37.  
  38.     /* ******************************************************************
  39.      *
  40.      *   Public definitions
  41.      *
  42.      ********************************************************************/
  43.  
  44.     // PM window class name for XCenter client (needed by XWPDaemon)
  45.     // #define WC_XCENTER_CLIENT     "XWPCenterClient"
  46.         // moved this to kernel.h because xwpdaemn.c includes this too
  47.         // and we don't want the stupid daemon to be recompiled every
  48.         // time this header changes
  49.         // V0.9.13 (2001-06-19) [umoeller]
  50.  
  51.     // button types (src\xcenter\w_objbutton.c)
  52.     #define BTF_OBJBUTTON       1
  53.     #define BTF_XBUTTON         2
  54.  
  55.     /*
  56.      *@@ XCENTERGLOBALS:
  57.      *      global data for a running XCenter instance.
  58.      *      This is created once per open XCenter.
  59.      *
  60.      *      A pointer to this one structure exists in each
  61.      *      XCENTERWIDGET instance so that the widgets
  62.      *      can access some of the data of the XCenter
  63.      *      they belong to.
  64.      *
  65.      *      In this structure, an XCenter instance
  66.      *      passes a number of variables to its member
  67.      *      widgets so that they can access some things
  68.      *      more quickly for convenience. This structure
  69.      *      is fully initialized at the time the widgets
  70.      *      are created, but values may change while the
  71.      *      XCenter is open (e.g. if the user changes
  72.      *      view settings in the XCenter settings notebook).
  73.      *
  74.      *      "Globals" isn't really a good name since
  75.      *      one of these structures is created for
  76.      *      each open XCenter (and there can be several),
  77.      *      but this is definitely more global than the
  78.      *      widget-specific structures.
  79.      */
  80.  
  81.     typedef struct _XCENTERGLOBALS
  82.     {
  83.         HAB                 hab;
  84.                     // anchor block of the XCenter thread and thus
  85.                     // all XCenter windows (including widgets)
  86.         HWND                hwndFrame,
  87.                     // be XCenter frame window (constant)
  88.                             hwndClient;
  89.                     // XCenter client (child of XCenter frame) (constant)
  90.  
  91.         PVOID               pCountrySettings;
  92.                     // country settings; this really points to a
  93.                     // COUNTRYSETTINGS structure (include\helpers\prfh.h)
  94.                     // and might be useful if you want to use settings
  95.                     // from the "Country" object (constant)
  96.  
  97.         ULONG               cyInnerClient;
  98.                     // height of inner client (same as height of all widgets!).
  99.                     // This is normally == cyWidgetmax unless the user has
  100.                     // resized the XCenter, but it will always be >= cyWidgetMax.
  101.                     // The "inner client" plus the 3D border width plus the
  102.                     // border spacing make up the full height of the XCenter.
  103.  
  104.                     // This can change while the XCenter is open.
  105.                     // This was changed with V0.9.9 (2001-03-09) [umoeller];
  106.                     // this field still always has the client height, but this
  107.                     // is no longer neccessarily the same as the tallest
  108.                     // widget (see cyWidgetMax below).
  109.  
  110.         ULONG               cxMiniIcon;
  111.                     // system mini-icon size (for convenience); either 16 or 20
  112.                     // (constant)
  113.  
  114.         LONG                lcol3DDark,
  115.                             lcol3DLight;
  116.                     // system colors for 3D frames (for convenience; RGB!) (constant)
  117.  
  118.         // the following are the width settings from the second "View"
  119.         // settings page;
  120.         // a widget may or may not want to consider these.
  121.         ULONG               flDisplayStyle;
  122.                     // XCenter display style flags;
  123.                     // a widget may or may not want to consider these.
  124.                     // Can be changed by the user while the XCenter is open.
  125.                     // These flags can be any combination of the following:
  126.  
  127.                     #define XCS_FLATBUTTONS         0x0001
  128.                     // -- XCS_FLATBUTTONS: paint buttons flat. If not set,
  129.                     //      paint them raised.
  130.  
  131.                     #define XCS_SUNKBORDERS         0x0002
  132.                     // -- XCS_SUNKBORDERS: paint static controls (e.g. CPU meter)
  133.                     //      with a "sunk" 3D frame. If not set, do not.
  134.  
  135.                     #define XCS_SIZINGBARS          0x0004
  136.                     // -- XCS_SIZINGBARS: XCenter should automatically paint
  137.                     //      sizing bars for sizeable widgets.
  138.  
  139.                     #define XCS_ALL3DBORDERS        0x0008
  140.                     // -- XCS_ALL3DBORDERS: XCenter should draw all four 3D
  141.                     //      borders around itself. If not set, it will only
  142.                     //      draw one border (the one towards the screen).
  143.  
  144.                     #define XCS_SPACINGLINES        0x0010      // added V0.9.13 (2001-06-19) [umoeller]
  145.                     // -- XCS_SPACINGLINES: XCenter should draw small 3D lines
  146.                     //      between the widgets too (V0.9.13 (2001-06-19) [umoeller]).
  147.  
  148.                     #define XCS_NOHATCHINUSE        0x0020      // added V0.9.16 (2001-10-24) [umoeller]
  149.                     // -- XCS_NOHATCHINUSE: XCenter should not add hatching to
  150.                     //      object widgets which represent open objects
  151.                     //      (V0.9.16 (2001-10-24) [umoeller])
  152.  
  153.         ULONG               ulPosition;
  154.                     // XCenter position on screen, if a widget cares...
  155.                     // can be changed by the user while the XCenter is open.
  156.                     // This is _one_ of the following:
  157.                     #define XCENTER_BOTTOM          0
  158.                     #define XCENTER_TOP             1
  159.                     // Left and right are not yet supported.
  160.  
  161.         ULONG               ul3DBorderWidth;
  162.                     // 3D border width; can be changed by user at any time
  163.         ULONG               ulBorderSpacing;
  164.                     // border spacing (added to 3D border width);
  165.                     // can be changed by user at any time
  166.         ULONG               ulWidgetSpacing;
  167.                     // spacing between widgets; can be changed by user at any time;
  168.                     // if flDisplayStyle also has XCS_SPACINGLINES set,
  169.                     // an extra 2 pixels will be added internally to this
  170.                     // value
  171.  
  172.         /*
  173.          *      The following fields have been added with
  174.          *      releases later than V0.9.7. Since they have
  175.          *      been added at the bottom, the structure is
  176.          *      still backward-compatible with old plugin
  177.          *      binaries... but you cannot use these new
  178.          *      fields unless you also require the corresponding
  179.          *      XCenter revision by using the "version" export @3.
  180.          */
  181.  
  182.         PVOID               pvXTimerSet;
  183.                     // XCenter timer set, which can be used by widgets
  184.                     // to start XTimers instead of regular PM timers.
  185.                     // This was added V0.9.9 (2001-03-07) [umoeller].
  186.                     // See src\helpers\timer.c for an introduction.
  187.                     // This pointer is really an XTIMERSET pointer but
  188.                     // has been declared as PVOID to avoid having to
  189.                     // #include include\helpers\timer.h all the time.
  190.                     // This is constant while the XCenter is open.
  191.  
  192.         ULONG               cyWidgetMax;
  193.                     // height of tallest widget == minimum height of client
  194.                     // V0.9.9 (2001-03-09) [umoeller]
  195.                     // This may change while the XCenter is open if
  196.                     // widgets are added or removed.
  197.  
  198.         LONG                lcolClientBackground;
  199.                     // background color of the XCenter client area,
  200.                     // in case a widget is interested.
  201.                     // V0.9.13 (2001-06-19) [umoeller]
  202.  
  203.         PVOID               pvSomSelf;
  204.                     // XCenter's somSelf object pointer. This is a
  205.                     // XCenter* pointer really, but has been declared
  206.                     // as PVOID so you won't have to include the WPS
  207.                     // SOM headers.
  208.                     // V0.9.13 (2001-06-19) [umoeller]
  209.  
  210.         HWND                hwndTooltip;
  211.                     // XCenter's tooltip control (comctl.c). This is
  212.                     // the one tooltip that is created for all widgets.
  213.                     // This member has been made public so widgets may
  214.                     // choose to work with the tooltip... but do not
  215.                     // mess with this unless you know what you're doing,
  216.                     // since all widgets share this one tooltip.
  217.                     // V0.9.13 (2001-06-21) [umoeller]
  218.  
  219.     } XCENTERGLOBALS, *PXCENTERGLOBALS;
  220.  
  221.     typedef const struct _XCENTERGLOBALS *PCXCENTERGLOBALS;
  222.  
  223.     // forward declaration
  224.     typedef struct _XCENTERWIDGET *PXCENTERWIDGET;
  225.  
  226.     BOOL APIENTRY ctrSetSetupString(LHANDLE hSetting, PCSZ pcszNewSetupString);
  227.     typedef BOOL APIENTRY CTRSETSETUPSTRING(LHANDLE hSetting, PCSZ pcszNewSetupString);
  228.     typedef CTRSETSETUPSTRING *PCTRSETSETUPSTRING;
  229.  
  230.     /*
  231.      *@@ WIDGETSETTINGSDLGDATA:
  232.      *      a bunch of data passed to a "show settings
  233.      *      dialog" function (WGTSHOWSETTINGSDLG), if
  234.      *      the widget has specified such a thing.
  235.      *
  236.      *      XCenter widget settings dialogs basically
  237.      *      work as follows:
  238.      *
  239.      *      1.  You must write a function that displays a modal
  240.      *          dialog. This function must have the following
  241.      *          prototype:
  242.      *
  243.      +              VOID EXPENTRY ShowSettingsDlg(PWIDGETSETTINGSDLGDATA pData)
  244.      *
  245.      *      2.  In the "init module" export, store that function
  246.      *          in the XCENTERWIDGETCLASS.pShowSettingsDlg field
  247.      *          for your widget class.
  248.      *
  249.      *          This will enable the "Properties" menu item
  250.      *          for the widget.
  251.      *
  252.      *      3.  Your function gets called when the user selects
  253.      *          "Properties". What that function does, doesn't
  254.      *          matter... it should however display a modal
  255.      *          dialog and update the widget's settings string
  256.      *          and call ctrSetSetupString with the "hSettings"
  257.      *          handle that was given to it in the
  258.      *          WIDGETSETTINGSDLGDATA structure. This will give
  259.      *          the widget the new settings.
  260.      *
  261.      *          The address of the ctrSetSetupString helper is
  262.      *          given to you in this structure so that you
  263.      *          won't have to import it from XFLDR.DLL.
  264.      *
  265.      *      If a widget class supports settings dialogs,
  266.      *      it must specify this in its XCENTERWIDGETCLASS.
  267.      *
  268.      *@@added V0.9.7 (2000-12-07) [umoeller]
  269.      *@@changed V0.9.9 (2001-02-06) [umoeller]: added pctrSetSetupString
  270.      */
  271.  
  272.     typedef struct _WIDGETSETTINGSDLGDATA
  273.     {
  274.         HWND                    hwndOwner;
  275.                     // proposed owner for settings dialog; this
  276.                     // will either be the HWND of the XCenter frame
  277.                     // or some other HWND, if the settings dialog
  278.                     // is displayed from elsewhere
  279.  
  280.         const char              *pcszSetupString;
  281.                     // present setup string (do not change)
  282.  
  283.         const LHANDLE           hSettings;
  284.                     // widget setting handle; this must
  285.                     // be passed to ctrSetSetupString;
  286.                     // DO NOT CHANGE
  287.  
  288.         PCXCENTERGLOBALS        pGlobals;
  289.                     // if != NULL, currently open XCenter
  290.                     // for which widget data is being changed.
  291.                     // If NULL, the XCenter isn't currently
  292.                     // open.
  293.  
  294.         PXCENTERWIDGET          pView;
  295.                     // if != NULL, currently open view
  296.                     // of the widget. If NULL, the widget
  297.                     // isn't currently open.
  298.  
  299.         PVOID                   pUser;
  300.                     // some room for additional data the
  301.                     // settings dialog might want
  302.  
  303.         /*
  304.          *      The following fields have been added with
  305.          *      releases later than V0.9.7. Since they have
  306.          *      been added at the bottom, the structure is
  307.          *      still backward-compatible with old plugin
  308.          *      binaries... but you cannot use these new
  309.          *      fields unless you also require the corresponding
  310.          *      XCenter revision by using the "version" export @3.
  311.          */
  312.  
  313.         PCTRSETSETUPSTRING      pctrSetSetupString;
  314.                     // ptr to ctrSetSetupString function in
  315.                     // src\shared\center.c; this must be
  316.                     // called by the settings dialog to
  317.                     // change the widget's setup string.
  318.                     // This pointer has been added with V0.9.9
  319.                     // to allow using settings dialog without
  320.                     // having to import this from XFLDR.DLL.
  321.  
  322.     } WIDGETSETTINGSDLGDATA, *PWIDGETSETTINGSDLGDATA;
  323.  
  324.     typedef VOID EXPENTRY WGTSHOWSETTINGSDLG(PWIDGETSETTINGSDLGDATA);
  325.     typedef WGTSHOWSETTINGSDLG *PWGTSHOWSETTINGSDLG;
  326.  
  327.     /*
  328.      *@@ XCENTERWIDGETCLASS:
  329.      *      describes one widget class which can be
  330.      *      used in an XCenter. Such a class can either
  331.      *      be internal or in a widget plugin DLL.
  332.      *
  333.      *      This structure _must_ have the same layout as
  334.      *      PLUGINCLASS.  It can redefine the ulUser* fields
  335.      *      to its liking, though.
  336.      *
  337.      *      The window procedure which implements the widget
  338.      *      class must be registered by a plug-in DLL when
  339.      *      its INIT callback gets called by the XCenter.
  340.      *
  341.      *      There are a few rules which must be followed
  342.      *      with the window procedures of the widget classes:
  343.      *
  344.      *      -- At the very least, the widget's window proc must
  345.      *         implement WM_CREATE, WM_PAINT, and (if cleanup
  346.      *         is necessary) WM_DESTROY. WM_PRESPARAMCHANGED
  347.      *         would also be nice to support fonts and colors
  348.      *         dropped on the widget.
  349.      *
  350.      *      -- On WM_CREATE, the widget receives a pointer to
  351.      *         its XCENTERWIDGET structure in mp1.
  352.      *
  353.      *         The first thing the widget _must_ do on WM_CREATE
  354.      *         is to store the XCENTERWIDGET pointer (from mp1)
  355.      *         in its QWL_USER window word by calling:
  356.      *
  357.      +              WinSetWindowPtr(hwnd, QWL_USER, mp1);
  358.      *
  359.      *      -- The XCenter communicates with the widget using
  360.      *         WM_CONTROL messages. SHORT1FROMMP(mp1), the
  361.      *         source window ID, is always ID_XCENTER_CLIENT.
  362.      *         SHORT2FROMMP(mp1), the notification code, can
  363.      *         be:
  364.      *
  365.      *         --  XN_QUERYSIZE: the XCenter wants to know the
  366.      *             widget's size.
  367.      *
  368.      *         --  XN_SETUPCHANGED: widget's setup string has
  369.      *             changed.
  370.      *
  371.      *         --  XN_BEGINANIMATE: the widget is about to be
  372.      *             shown/hidden.
  373.      *
  374.      *         --  XN_ENDANIMATE: the widget is now fully shown/hidden.
  375.      *
  376.      *         --  XN_HITTEST:  for transparent widgets, the XCenter
  377.      *             wants to know if the specified location is covered.
  378.      *
  379.      *      -- All unprocessed notifications must be routed
  380.      *         to ctrDefWidgetProc instead of WinDefWindowProc.
  381.      *         Do not swallow unprocessed messages.
  382.      *
  383.      *      -- You must never use WinSetWindowPos on your widget
  384.      *         window yourself because this will solidly confuse
  385.      *         the XCenter widget formatting. If you want your
  386.      *         widget window to be resized, post XCM_SETWIDGETSIZE
  387.      *         to the widget's parent instead, which will resize
  388.      *         your widget properly and also reformat the other
  389.      *         widgets, if necessary.
  390.      *
  391.      *      -- All unprocessed messages should be routed
  392.      *         to ctrDefWidgetProc instead of WinDefWindowProc.
  393.      *
  394.      *      -- WM_MENUEND must _always_ be passed on after your
  395.      *         own processing (if any) to remove source emphasis
  396.      *         for popup menus.
  397.      *
  398.      *      -- WM_DESTROY must _always_ be passed on after
  399.      *         your own cleanup code to avoid memory leaks,
  400.      *         because this function performs important cleanup
  401.      *         as well.
  402.      *
  403.      *      -- WM_COMMAND command values above 0x7f00 are reserved.
  404.      *         If you extend the context menu given to you in
  405.      *         XCENTERWIDGET.hwndContextMenu, you must use
  406.      *         menu item IDs < 0x7f00. This has been changed
  407.      *         with V0.9.11 (2001-04-25) [umoeller] to avoid
  408.      *         conflicts with the WPS menu item IDs, sorry.
  409.      *
  410.      *      <B>Resource management</B>
  411.      *
  412.      *      You should always be aware that your widget is a PM
  413.      *      window in the WPS process. As a result, all resource
  414.      *      leaks that you produce in your widget code will affect
  415.      *      the entire WPS, and all crashes will too.
  416.      *
  417.      *      As a general rule, the XCenter will free all widget
  418.      *      resources that it has allocated itself (such as the
  419.      *      structures that were created for it). By contrast,
  420.      *      if you allocate something yourself, it is your
  421.      *      responsibility to free it. This applies especially
  422.      *      to XCENTERWIDGET.pUser, which is your general pointer
  423.      *      to store widget-specific things.
  424.      *
  425.      *      Of course the same rules apply to PM resources such
  426.      *      as icons, bitmaps, regions, memory PS's etc. You can
  427.      *      quickly bring down the WPS if you forget to free those.
  428.      *      Same thing if you start additional threads in your
  429.      *      widget code.
  430.      *
  431.      *      This is especially important because widget windows
  432.      *      can be created and destroyed without the widgets
  433.      *      cooperation. For example, if the widget is in a tray,
  434.      *      it will be created and destroyed when the current
  435.      *      tray changes. If you leak something in this situation,
  436.      *      this can quickly become a major problem.
  437.      *
  438.      *      I also recommend to use exception handling in your
  439.      *      widget code to properly clean up things if something
  440.      *      goes wrong. As said in center.c, do not use exit
  441.      *      lists because that will cause DLL unloading to fail.
  442.      *
  443.      *      <B>Tooltip support</B>
  444.      *
  445.      *      If your widget class has the WGTF_TOOLTIP flag set,
  446.      *      it will receive WM_CONTROL with TTN_* notifications
  447.      *      and the source window ID set to ID_XCENTER_TOOLTIP.
  448.      *      If it responds to TTN_NEEDTEXT, it must fill the
  449.      *      TOOLTIPTEXT pointed to by mp2. See include\helpers\comctl.h
  450.      *      for details.
  451.      *
  452.      *      In addition, the widget will also receive the TTN_SHOW
  453.      *      and TTN_POP notifications when the tooltip is being
  454.      *      shown or hidden above it.
  455.      *
  456.      *      <B>Trayable widgets</B>
  457.      *
  458.      *      If your widget is supposed to be trayable (i.e.
  459.      *      the WGTF_TRAYABLE flag is set in the XCENTERWIDGETCLASS),
  460.      *      it must conform to a few extra rules:
  461.      *
  462.      *      -- Trayable widgets cannot be sizeable or greedy
  463.      *         because the tray widget itself is sizeable.
  464.      *
  465.      *      -- You must never assume that the parent window of
  466.      *         your widget really is the XCenter client. It can
  467.      *         also be a tray widget. Always use
  468.      *         WinQueryWindow(hwndWidget, QW_PARENT) to find your
  469.      *         parent window, which will properly give you either
  470.      *         the XCenter client or the tray widget.
  471.      *
  472.      *      -- If you use XCM_* messages, never post them to the
  473.      *         XCenter client window (whose handle is available
  474.      *         thru XCENTERGLOBALS). All XCM_* essages are understood
  475.      *         by the tray widget also, and if your widget is in a tray,
  476.      *         it must post them to the tray instead of the client.
  477.      *
  478.      *      -- Your widget must be prepared for being created or
  479.      *         destroyed at times other than XCenter creation or
  480.      *         destruction because the tray widget will do this
  481.      *         when the current tray is switched.
  482.      */
  483.  
  484.     typedef struct _XCENTERWIDGETCLASS
  485.     {
  486.         const char      *pcszPMClass;
  487.                 // PM window class name of this widget class (can be shared among
  488.                 // several widget classes). A plugin DLL is responsible for
  489.                 // registering this window class when it's loaded.
  490.                 // Naturally, this must be unique on the system.
  491.  
  492.         ULONG           ulExtra;
  493.                 // additional identifiers the class might need if the
  494.                 // same PM window class is used for several widget classes.
  495.                 // This is not used by the XCenter, but you can access it
  496.                 // during WM_CREATE so you can differentiate between several
  497.                 // widget classes in the same window proc. You must copy this
  498.                 // to your private widget data then.
  499.                 // For example, MONITORS.DLL uses this to differentiate
  500.                 // between the various monitor widget classes.
  501.  
  502.         const char      *pcszWidgetClass;
  503.                 // internal widget class name; this is used to identify
  504.                 // the class. This must be unique on the system and must
  505.                 // not contain special characters like commas, brackets,
  506.                 // etc. Besides, since this must work with all codepages,
  507.                 // use only ASCII characters <= 127, and use an English
  508.                 // name always.
  509.                 // A valid name would be "MySampleClass".
  510.                 // This is stored internally in the XCenter data and is
  511.                 // used whenever the XCenter is opened to create all the
  512.                 // widgets from the respective widget classes. In other
  513.                 // words, this is the class identifier and must never
  514.                 // change between several releases or different NLS versions
  515.                 // of your plugin DLL, or otherwise widget creation will fail.
  516.                 // Choose this name carefully.
  517.  
  518.         const char      *pcszClassTitle;
  519.                 // explanatory widget class title, which is shown to the
  520.                 // user in the "Add widget" popup menu. Example: "Sample widget".
  521.                 // This is not used to identify the class internally and may
  522.                 // change between releases and NLS versions. So you can set
  523.                 // this to a language-specific string.
  524.                 // Note: If this has the highest bit set, it is assumed to
  525.                 // be a string resource ID in the XWorkplace NLS DLL instead
  526.                 // of a real string:
  527.                 #define XCENTER_STRING_RESOURCE     0x80000000
  528.                             // V0.9.19 (2002-05-07) [umoeller]
  529.  
  530.         ULONG           ulClassFlags;
  531.                 // WGTF_* flags; any combination of the following:
  532.  
  533.                 #define WGTF_SIZEABLE               0x0001
  534.                 // -- WGTF_SIZEABLE: widget window can be resized with
  535.                 //    the mouse by the user. A sizing bar is automatically
  536.                 //    painted by the XCenter engine then.
  537.  
  538.                 #define WGTF_NOUSERCREATE           0x0002
  539.                 // -- WGTF_NOUSERCREATE: do not show this class in
  540.                 //    the "add widget" menu, and do not allow creating
  541.                 //    instances of this in the XCenter settings notebook.
  542.                 //    This is used for the object button widget, which
  543.                 //    can only be created through drag'n'drop. This flag
  544.                 //    isn't terribly useful for plug-in DLLs because
  545.                 //    without support in the XCenter engine the widget
  546.                 //    could then not be created at all.
  547.  
  548.                 #define WGTF_UNIQUEPERXCENTER       0x0004
  549.                 // -- WGTF_UNIQUEPERXCENTER: only one widget of this class
  550.                 //    should be created per XCenter.
  551.  
  552.                 #define WGTF_UNIQUEGLOBAL          (0x0008 + 0x0004)
  553.                 // -- WGTF_UNIQUEGLOBAL: only one widget of this class
  554.                 //    should be created in all XCenters on the system.
  555.                 //    This implies WGTF_UNIQUEPERXCENTER.
  556.  
  557.                 #define WGTF_TOOLTIP                0x0010
  558.                 // -- WGTF_TOOLTIP: if set, the widget has a tooltip
  559.                 //    and will receive WM_CONTROL messages with the
  560.                 //    TTN_NEEDTEXT, TTN_SHOW, or TTN_POP notification codes
  561.                 //    (see helpers\comctl.h).
  562.                 //    The window ID of the tooltip control is ID_XCENTER_TOOLTIP.
  563.                 //    See XCENTERWIDGETCLASS for tooltip handling.
  564.  
  565.                 #define WGTF_TOOLTIP_AT_MOUSE      (0x0020 + 0x0010)
  566.                 // -- WGTF_TOOLTIP_AT_MOUSE: like WGTF_TOOPTIP, but the
  567.                 //    tooltip is not centered above the widget, but put
  568.                 //    at the mouse position instead.
  569.                 //    This implies WGTF_TOOLTIP.
  570.  
  571.                 #define WGTF_TRANSPARENT            0x0040
  572.                 // -- WGTF_TRANSPARENT: some parts of the widget window
  573.                 //    are transparent.  The widget will receive WM_CONTROL
  574.                 //    messages with the XN_HITTEST notification code.
  575.                 //    If the widget returns FALSE to the notification,
  576.                 //    the action will be forwarded to its parent (the
  577.                 //    XCenter client or a tray widget).
  578.  
  579.                 #define WGTF_NONFOCUSTRAVERSABLE    0x0100
  580.                 //    Reserved for future use.
  581.  
  582.                 #define WGTF_TRAYABLE               0x0200
  583.                 // -- WGTF_TRAYABLE: widget is "trayable", that is, it
  584.                 //    supports being created inside a tray widget.
  585.                 //    Note: Restrictions apply if you want your widget
  586.                 //    to be trayable. See above.
  587.  
  588.                 #define WGTF_CANTAKECENTERHOTKEY    0x0400
  589.                 // -- WGTF_CANTAKECENTERHOTKEY: signals that the widget is
  590.                 //    willing to take action when the XCenter gets
  591.                 //    resurfaced via its object hotkey.
  592.                 //    The widget will then receive WM_CONTROL with
  593.                 //    the XN_CENTERHOTKEYPRESSED code; see remarks for
  594.                 //    XN_CENTERHOTKEYPRESSED.
  595.                 //    V0.9.19 (2002-04-17) [umoeller]
  596.  
  597.                 #define WGTF_CONFIRMREMOVE          0x0800
  598.                 // -- WGTF_CONFIRMREMOVE: adds "..." to the "Remove widget"
  599.                 //    context menu item and confirms removal if the user
  600.                 //    selects that.
  601.                 //    V0.9.20 (2002-08-08) [umoeller]
  602.  
  603.         PWGTSHOWSETTINGSDLG pShowSettingsDlg;
  604.                 // if the widget supports a settings dialog,
  605.                 // it must set this func pointer to a procedure
  606.                 // that will show that dialog. If this is != NULL,
  607.                 // the "Properties" menu item and the button in
  608.                 // the widgets list of the XCenter settings notebook
  609.                 // will be enabled. See WIDGETSETTINGSDLGDATA for
  610.                 // details about how to implement widget settings dialogs.
  611.  
  612.     } XCENTERWIDGETCLASS, *PXCENTERWIDGETCLASS;
  613.  
  614.     typedef const struct _XCENTERWIDGETCLASS *PCXCENTERWIDGETCLASS;
  615.  
  616.     /*
  617.      *@@ XCENTERWIDGETSETTING:
  618.      *      describes one widget to be created. One instance
  619.      *      of this is created for each widget that the
  620.      *      user has configured for a widget.
  621.      *
  622.      *      An array of these is stored in packed form in the
  623.      *      XCenter instance data and describes all widgets
  624.      *      in the XCenter. Widget classes normally don't need
  625.      *      this.
  626.      *
  627.      *      An array of these is returned by XCenter::xwpQueryWidgets.
  628.      */
  629.  
  630.     typedef struct _XCENTERWIDGETSETTING
  631.     {
  632.         PSZ             pszWidgetClass;   // widget class name;
  633.                     // we cannot use the binary PXCENTERWIDGETCLASS pointer
  634.                     // here because these structures are dynamically unloaded...
  635.                     // use ctrpFindClass to find the XCENTERWIDGETCLASS ptr.
  636.         PSZ             pszSetupString;
  637.                     // widget-class-specific setup string; can be NULL
  638.  
  639.             // Note: both pointers are assumed to be allocated
  640.             // using malloc() or strdup() and are automatically
  641.             // freed.
  642.  
  643.     } XCENTERWIDGETSETTING, *PXCENTERWIDGETSETTING;
  644.  
  645.     /*
  646.      *@@ XCENTERWIDGET:
  647.      *      public structure to hold data for an XCenter
  648.      *      widget, i.e. a PM window in the XCenter client
  649.      *      area.
  650.      *
  651.      *      Each XCenter widget is a separate window,
  652.      *      being a child window of the XCenter client,
  653.      *      which in turn is a child of the XCenter frame.
  654.      *      The exception is a widget in a tray, which is
  655.      *      a child of a tray widget, which in turn is a
  656.      *      child of the XCenter client.
  657.      *
  658.      *      This structure is created once for each widget
  659.      *      and passed to each widget in mp1 of WM_CREATE.
  660.      *      The first thing a widget must do on WM_CREATE
  661.      *      is to store a pointer to this structure in its
  662.      *      QWL_USER window word.
  663.      *
  664.      *      The widget can allocate another widget-specific
  665.      *      buffer and store its pointer into the pUser
  666.      *      field. This is strongly recommended because
  667.      *      otherwise your widget will have no place to
  668.      *      store its instance data.
  669.      *
  670.      *      This structure is automatically freed by the
  671.      *      XCenter when the widget is destroyed. However,
  672.      *      if you allocated more memory for pUser, it is
  673.      *      your own responsibility to free that on WM_DESTROY.
  674.      *      General rule: The widget must clean up what it
  675.      *      allocated itself.
  676.      *
  677.      *      See XCENTERWIDGETCLASS for rules that a widget
  678.      *      window proc must conform to.
  679.      */
  680.  
  681.     typedef struct _XCENTERWIDGET
  682.     {
  683.         /*
  684.          *  Informational fields:
  685.          *      all these are meant for reading only
  686.          *      and set up by the XCenter for the widget.
  687.          */
  688.  
  689.         HWND        hwndWidget;
  690.                 // window handle of this widget; this is valid
  691.                 // only _after_ WM_CREATE.
  692.  
  693.         HAB         habWidget;
  694.                 // widget's anchor block (copied for convenience).
  695.  
  696.         PFNWP       pfnwpDefWidgetProc;
  697.                 // address of default widget window procedure. This
  698.                 // always points to ctrDefWidgetProc (in
  699.                 // src/shared/center.c). The widget's own window
  700.                 // proc must pass all unprocessed messages (and a
  701.                 // few more) to this instead of WinDefWindowProc.
  702.                 // See XCENTERWIDGETCLASS for details.
  703.  
  704.         PCXCENTERGLOBALS pGlobals;
  705.                 // ptr to client/frame window data (do not change)
  706.  
  707.         PCXCENTERWIDGETCLASS pWidgetClass;
  708.                 // widget class this widget was created from;
  709.                 // this ptr is only valid during WM_CREATE and
  710.                 // always NULL afterwards
  711.  
  712.         PCSZ        pcszWidgetClass;
  713.                 // internal name of the widget's class; this
  714.                 // is the same as pWidgetClass->pcszWidgetClass,
  715.                 // but this is valid after WM_CREATE.
  716.                 // DO NOT CHANGE it, the XCenter relies on this!
  717.         ULONG       ulClassFlags;
  718.                 // class flags copied from XCENTERWIDGETCLASS.
  719.  
  720.         PCSZ        pcszSetupString;
  721.                 // class-specific setup string. This field
  722.                 // is only valid during WM_CREATE and then holds
  723.                 // the setup string which was last stored with
  724.                 // the widget. The pointer can be NULL if no
  725.                 // setup string exists. After WM_CREATE, the
  726.                 // pointer is set to NULL always.
  727.                 // The widget should use this string to initialize
  728.                 // itself. When its instance data changes, it
  729.                 // should send XCM_SAVESETUP to its parent
  730.                 // so that the XCenter can record the new setup
  731.                 // string.
  732.  
  733.         /*
  734.          *  Setup fields:
  735.          *      all these should be set up by the widget
  736.          *      (normally during WM_CREATE). The XCenter
  737.          *      reads these fields to find out more about
  738.          *      the widget's wishes.
  739.          *
  740.          *      All these fields are initialized to safe
  741.          *      defaults, which are probably not suitable
  742.          *      for most widgets though.
  743.          */
  744.  
  745.         BOOL        fSizeable;
  746.                 // if TRUE, the widget is sizeable with the mouse.
  747.                 // This is initially set to TRUE if the widget's
  748.                 // class has the WGTF_SIZEABLE flag, but can be
  749.                 // changed by the widget at any time.
  750.                 // NOTE: If your widget is "greedy", i.e. wants
  751.                 // all remaining size on the XCenter bar (by
  752.                 // returning -1 for cx with WM_CONTROL and
  753.                 // XCN_QUERYSIZE), it cannot be sizeable.
  754.  
  755.         HWND        hwndContextMenu;
  756.                 // default context menu for this widget.
  757.                 // The XCenter loads a the same standard context menu
  758.                 // for each widget, which is displayed on WM_CONTEXTMENU
  759.                 // in ctrDefWidgetProc. Normally, the widget needs not
  760.                 // do anything to have the context menu displayed;
  761.                 // ctrDefWidgetProc takes care of this. However, you may
  762.                 // safely manipulate this context menu if you want to
  763.                 // insert/remove items.
  764.                 // The menu in here gets destroyed using WinDestroyWindow
  765.                 // when the widget window is destroyed.
  766.                 // This is only valid after WM_CREATE.
  767.  
  768.         PCSZ        pcszHelpLibrary;
  769.         ULONG       ulHelpPanelID;
  770.                 // if these two are specified, the XCenter will
  771.                 // enable the "Help" item in the widget's context
  772.                 // menu and display the specified help panel when
  773.                 // the menu item is selected. Both default to NULL.
  774.  
  775.         /*
  776.          *  Additional fields:
  777.          */
  778.  
  779.         PVOID       pUser;
  780.                 // user data allocated by window class; this is
  781.                 // initially NULL, but you can use this for your
  782.                 // own data (which you must clean up yourself on
  783.                 // WM_DESTROY).
  784.  
  785.         PVOID       pvWidgetSetting;
  786.                 // private pointer for tray widget. DO NOT USE THIS.
  787.                 // V0.9.13 (2001-06-21) [umoeller]
  788.  
  789.     } XCENTERWIDGET;
  790.  
  791.     /* ******************************************************************
  792.      *
  793.      *   Public widget helpers (exported from XFLDR.DLL)
  794.      *
  795.      ********************************************************************/
  796.  
  797.     // All these are specified as both simple prototypes and
  798.     // function pointer declarations so that widget classes
  799.     // can import these functions from XFLDR.DLL in the init
  800.     // export.
  801.  
  802.     PSZ APIENTRY ctrScanSetupString(PCSZ pcszSetupString,
  803.                                     PCSZ pcszKeyword);
  804.     typedef PSZ APIENTRY CTRSCANSETUPSTRING(PCSZ pcszSetupString,
  805.                                             PCSZ pcszKeyword);
  806.     typedef CTRSCANSETUPSTRING *PCTRSCANSETUPSTRING;
  807.  
  808.     LONG APIENTRY ctrParseColorString(PCSZ p);
  809.     typedef LONG APIENTRY CTRPARSECOLORSTRING(PCSZ p);
  810.     typedef CTRPARSECOLORSTRING *PCTRPARSECOLORSTRING;
  811.  
  812.     VOID APIENTRY ctrFreeSetupValue(PSZ p);
  813.     typedef VOID APIENTRY CTRFREESETUPVALUE(PSZ p);
  814.     typedef CTRFREESETUPVALUE *PCTRFREESETUPVALUE;
  815.  
  816.     // ctrSetSetupString has been defined above
  817.  
  818.     BOOL APIENTRY ctrDisplayHelp(PCXCENTERGLOBALS pGlobals,
  819.                                  PCSZ pcszHelpFile,
  820.                                  ULONG ulHelpPanelID);
  821.     typedef BOOL APIENTRY CTRDISPLAYHELP(PCXCENTERGLOBALS pGlobals,
  822.                                          PCSZ pcszHelpFile,
  823.                                          ULONG ulHelpPanelID);
  824.     typedef CTRDISPLAYHELP *PCTRDISPLAYHELP;
  825.  
  826.     VOID APIENTRY ctrShowContextMenu(PXCENTERWIDGET pWidget, HWND hwndContextMenu);
  827.     typedef VOID APIENTRY CTRSHOWCONTEXTMENU(PXCENTERWIDGET pWidget, HWND hwndContextMenu);
  828.     typedef CTRSHOWCONTEXTMENU *PCTRSHOWCONTEXTMENU;
  829.  
  830.     VOID APIENTRY ctrPaintStaticWidgetBorder(HPS hps, PXCENTERWIDGET pWidget);
  831.     typedef VOID APIENTRY CTRPAINTSTATICWIDGETBORDER(HPS hps, PXCENTERWIDGET pWidget);
  832.     typedef CTRPAINTSTATICWIDGETBORDER *PCTRPAINTSTATICWIDGETBORDER;
  833.  
  834.     VOID APIENTRY ctrDrawWidgetEmphasis(PXCENTERWIDGET pWidget, BOOL fRemove);
  835.     typedef VOID APIENTRY CTRDRAWWIDGETEMPHASIS(PXCENTERWIDGET pWidget, BOOL fRemove);
  836.     typedef CTRDRAWWIDGETEMPHASIS *PCTRDRAWWIDGETEMPHASIS;
  837.  
  838.     VOID APIENTRY ctrPlaceAndPopupMenu(HWND hwndOwner, HWND hwndMenu, BOOL fAbove);
  839.     typedef VOID APIENTRY CTRPLACEANDPOPUPMENU(HWND hwndOwner, HWND hwndMenu, BOOL fAbove);
  840.     typedef CTRPLACEANDPOPUPMENU *PCTRPLACEANDPOPUPMENU;
  841.  
  842.     MRESULT EXPENTRY ctrDefWidgetProc(HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2);
  843.                 // a pointer to this is in XCENTERWIDGET if the widget
  844.                 // is a non-container widget
  845.     typedef MRESULT EXPENTRY CTRDEFWIDGETPROC(HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2);
  846.     typedef CTRDEFWIDGETPROC *PCTRDEFWIDGETPROC;
  847.  
  848.     /* ******************************************************************
  849.      *
  850.      *   Open XCenter views
  851.      *
  852.      ********************************************************************/
  853.  
  854.     BOOL APIENTRY ctrIsXCenterView(HWND hwndFrame);
  855.     typedef BOOL APIENTRY CTRISXCENTERVIEW(HWND hwndFrame);
  856.     typedef CTRISXCENTERVIEW *PCTRISXCENTERVIEW;
  857.                 // this function was added with V0.9.16
  858.  
  859.     /* ******************************************************************
  860.      *
  861.      *   WM_CONTROL notification codes _from_ XCenter client
  862.      *
  863.      ********************************************************************/
  864.  
  865.     #define ID_XCENTER_CLIENT           7000
  866.     #define ID_XCENTER_TOOLTIP          7001
  867.  
  868.     /*
  869.      *@@ XN_QUERYSIZE:
  870.      *      notification code for WM_CONTROL sent from
  871.      *      the XCenter to a widget when it needs to
  872.      *      know its desired size. This comes in once
  873.      *      after WM_CREATE and may come in again later
  874.      *      if the user changes XCenter view settings.
  875.      *
  876.      *      Parameters:
  877.      *
  878.      *      -- SHORT1FROMMP(mp1): ID, always ID_XCENTER_CLIENT.
  879.      *
  880.      *      -- SHORT2FROMMP(mp1): notify code (XN_QUERYSIZE).
  881.      *
  882.      *      -- PSIZEL mp2: pointer to a SIZEL structure in which
  883.      *                     the widget must fill in its desired
  884.      *                     size.
  885.      *
  886.      *      The widget must return TRUE if it has put its
  887.      *      desired size into the SIZEL structure. Otherwise
  888.      *      the XCenter will assume some dumb default for
  889.      *      the widget size.
  890.      *
  891.      *      As a special case, a widget can put -1 into the
  892.      *      cx field of the SIZEL structure. It will then
  893.      *      receive all remaining space on the XCenter bar
  894.      *      ("greedy" widgets). This is what the window list
  895.      *      widget does, for example.
  896.      *
  897.      *      If several widgets request to be "greedy", the
  898.      *      remaining space on the XCenter bar is evenly
  899.      *      distributed among the greedy widgets.
  900.      *
  901.      *      After all widgets have been created, the XCenter
  902.      *      (and all widgets) are resized to have the largest
  903.      *      cy requested. As a result, your window proc cannot
  904.      *      assume that it will always have the size it
  905.      *      requested.
  906.      *
  907.      *@@added V0.9.7 (2000-12-14) [umoeller]
  908.      */
  909.  
  910.     #define XN_QUERYSIZE                1
  911.  
  912.     /*
  913.      *@@ XN_SETUPCHANGED:
  914.      *      notification code for WM_CONTROL sent from
  915.      *      the XCenter to a widget when its setup string
  916.      *      has changed.
  917.      *
  918.      *      Parameters:
  919.      *
  920.      *      -- SHORT1FROMMP(mp1): ID, always ID_XCENTER_CLIENT.
  921.      *
  922.      *      -- SHORT2FROMMP(mp1): notify code (XN_SETUPCHANGED).
  923.      *
  924.      *      -- const char* mp2: pointer to a new zero-termianted
  925.      *                          setup string.
  926.      *
  927.      *      The widget must return TRUE if it has processed
  928.      *      the setup string successfully.
  929.      *
  930.      *      This gets sent to an open widget when
  931.      *      ctrSetSetupString has been invoked on it to allow
  932.      *      it to update its display. This normally happens
  933.      *      when its settings dialog saves a new setup string.
  934.      *
  935.      *@@added V0.9.7 (2000-12-13) [umoeller]
  936.      */
  937.  
  938.     #define XN_SETUPCHANGED             2
  939.  
  940.     /*
  941.      *@@ XN_OBJECTDESTROYED:
  942.      *      notification code for WM_CONTROL posted (!)
  943.      *      to a widget if it has registered itself with
  944.      *      XFldObject::xwpSetWidgetNotify.
  945.      *
  946.      *      This is a last chance for the widget to clean
  947.      *      up itself when an object that it relies on gets
  948.      *      destroyed (deleted or made dormant). This message
  949.      *      is posted from XFldObject::wpUnInitData.
  950.      *
  951.      *      Parameters:
  952.      *
  953.      *      -- SHORT1FROMMP(mp1): ID, always ID_XCENTER_CLIENT.
  954.      *
  955.      *      -- SHORT2FROMMP(mp1): notify code (XN_OBJECTDESTROYED).
  956.      *
  957.      *      -- WPObject* mp2: SOM object pointer of object
  958.      *                        being destroyed. NOTE: This pointer
  959.      *                        is no longer valid. Do not invoke
  960.      *                        any SOM methods on it.
  961.      *
  962.      *@@added V0.9.7 (2001-01-03) [umoeller]
  963.      */
  964.  
  965.     #define XN_OBJECTDESTROYED          3
  966.  
  967.     /*
  968.      * XN_QUERYSETUP:
  969.      *      notification code for WM_CONTROL sent to a widget
  970.      *      when the sender needs to know the widget's setup string.
  971.      *
  972.      *      Parameters:
  973.      *
  974.      *      -- SHORT1FROMMP(mp1): ID, always ID_XCENTER_CLIENT.
  975.      *
  976.      *      -- SHORT2FROMMP(mp1): notify code (XN_QUERYSETUP).
  977.      *
  978.      *      -- char *mp2: buffer into which the setup string is
  979.      *                    copied.  It can be NULL, in which case
  980.      *                    nothing is copied.  Otherwise, it is
  981.      *                    expected to contain enough room for the
  982.      *                    whole setup string.
  983.      *
  984.      *      The widget must return the minimum required size needed
  985.      *      to store the setup string (even if mp2 is NULL).
  986.      *
  987.      *added V0.9.9 (2001-03-01) [lafaix]
  988.      */
  989.  
  990.     // #define XN_QUERYSETUP               4
  991.  
  992.     // flags for XN_BEGINANIMATE and XN_ENDANIMATE
  993.     #define XAF_SHOW                    1
  994.     #define XAF_HIDE                    2
  995.  
  996.     /*
  997.      *@@ XN_BEGINANIMATE:
  998.      *      notification code for WM_CONTROL sent to a widget from
  999.      *      an XCenter when it is about to begin animating.
  1000.      *
  1001.      *      Parameters:
  1002.      *
  1003.      *      -- SHORT1FROMMP(mp1): ID, always ID_XCENTER_CLIENT.
  1004.      *
  1005.      *      -- SHORT2FROMMP(mp1): notify code (XN_BEGINANIMATE).
  1006.      *
  1007.      *      -- ULONG mp2: XAF_SHOW if the parent initiate a 'show' animation,
  1008.      *                    XAF_HIDE if the parent initiate a 'hide' animation.
  1009.      *
  1010.      *      This notification is sent regardless of whether the XCenter
  1011.      *      actually does animation.  If it does no animation,
  1012.      *      XN_ENDANIMATE immediately follows XN_BEGINANIMATE.
  1013.      *
  1014.      *      An active widget can react to this message to start or
  1015.      *      stop doing something.  For example, a gauge widget can
  1016.      *      choose to stop running when the container is hidden, to
  1017.      *      save CPU cycles.
  1018.      *
  1019.      *@added V0.9.9 (2001-03-01) [lafaix]
  1020.      */
  1021.  
  1022.     #define XN_BEGINANIMATE             5
  1023.  
  1024.     /*
  1025.      *@@ XN_ENDANIMATE:
  1026.      *      notification code for WM_CONTROL sent to a widget from
  1027.      *      an XCenter when it has ended animating.
  1028.      *
  1029.      *      Parameters:
  1030.      *
  1031.      *      -- SHORT1FROMMP(mp1): ID, always ID_XCENTER_CLIENT.
  1032.      *
  1033.      *      -- SHORT2FROMMP(mp1): notify code (XN_ENDANIMATE).
  1034.      *
  1035.      *      -- ULONG mp2: XAF_SHOW if the parent ended a 'show' animation,
  1036.      *                    XAF_HIDE if the parent ended a 'hide' animation.
  1037.      *
  1038.      *      This notification is sent regardless of whether the XCenter
  1039.      *      actually does animation.  If it does no animation,
  1040.      *      XN_ENDANIMATE immediately follows XN_BEGINANIMATE.
  1041.      *
  1042.      *      An active widget can react to this message to start or
  1043.      *      stop doing something.  For example, a gauge widget can
  1044.      *      choose to stop running when the container is hidden, to
  1045.      *      save CPU cycles.
  1046.      *
  1047.      *@added V0.9.9 (2001-03-01) [lafaix]
  1048.      */
  1049.  
  1050.     #define XN_ENDANIMATE               6
  1051.  
  1052.     /*
  1053.      * XN_QUERYWIDGETCOUNT:
  1054.      *      notification code for WM_CONTROL sent from the XCenter
  1055.      *      to a widget when it needs to know how many elements a
  1056.      *      container-widget contains.
  1057.      *
  1058.      *      Parameters:
  1059.      *
  1060.      *      -- SHORT1FROMMP(mp1): ID, always ID_XCENTER_CLIENT.
  1061.      *
  1062.      *      -- SHORT2FROMMP(mp1): notify code (XN_QUERYWIDGETCOUNT).
  1063.      *
  1064.      *      -- PULONG mp2: pointer to an ULONG in which the widget
  1065.      *                     must fill in its widget count.
  1066.      *
  1067.      *      The widgets count must only include first level elements.
  1068.      *      That is, if a container contains other containers, the
  1069.      *      elements in those sub-containers should not be included.
  1070.      *
  1071.      *      The widget must return TRUE if it has put its count in the
  1072.      *      ULONG.  Otherwise, the XCenter will assume some dumb default
  1073.      *      for the count.
  1074.      *
  1075.      *added V0.9.9 (2001-02-23) [lafaix]
  1076.      *changed V0.9.9 (2001-03-11) [lafaix]: uses a PULONG to return the count.
  1077.      */
  1078.  
  1079.     // #define XN_QUERYWIDGETCOUNT         7
  1080.  
  1081.     /*
  1082.      * XN_QUERYWIDGET:
  1083.      *      notification code for WM_CONTROL sent from the XCenter
  1084.      *      to a widget when it needs to know the widget present at
  1085.      *      a given position.
  1086.      *
  1087.      *      Parameters:
  1088.      *
  1089.      *      -- SHORT1FROMMP(mp1): ID, always ID_XCENTER_CLIENT.
  1090.      *
  1091.      *      -- SHORT2FROMMP(mp1): notify code (XN_QUERYWIDGET).
  1092.      *
  1093.      *      -- ULONG mp2: widget index (0 is the first widget).
  1094.      *
  1095.      *      The widget must return 0 if no widget exists at that index.
  1096.      *      Otherwise it must return a pointer to the corresponding
  1097.      *      XCENTERWIDGET structure.
  1098.      *
  1099.      *added V0.9.9 (2001-02-23) [lafaix]
  1100.      */
  1101.  
  1102.     // #define XN_QUERYWIDGET              8
  1103.  
  1104.     // structure needed for XN_INSERTWIDGET
  1105.     typedef struct _WIDGETINFO
  1106.     {
  1107.         SHORT          sOffset;
  1108.                    // either WGT_END or the 0-based offset
  1109.         PXCENTERWIDGET pWidget;
  1110.                    // the widget to be inserted
  1111.     } WIDGETINFO, *PWIDGETINFO;
  1112.  
  1113.     // flags and return values for XN_INSERTWIDGET:
  1114.     #define WGT_END                     (-1)
  1115.     #define WGT_ERROR                   (-1)
  1116.  
  1117.     /*
  1118.      * XN_INSERTWIDGET:
  1119.      *      notification code for WM_CONTROL sent from the XCenter
  1120.      *      to a widget when it needs to add a widget at a specified
  1121.      *      offset to a container-widget.
  1122.      *
  1123.      *      Parameters:
  1124.      *
  1125.      *      -- SHORT1FROMMP(mp1): ID, always ID_XCENTER_CLIENT.
  1126.      *
  1127.      *      -- SHORT2FROMMP(mp1): notify code (XN_INSERTWIDGET).
  1128.      *
  1129.      *      -- PWIDGETINFO mp2: a pointer to a WIDGETINFO structure
  1130.      *                          that details the insertion.
  1131.      *
  1132.      *      The widget must return WGT_ERROR if the insertion failed.
  1133.      *      Otherwise it must return the offset of the widget following
  1134.      *      the inserted one.
  1135.      *
  1136.      *added V0.9.9 (2001-02-23) [lafaix]
  1137.      */
  1138.  
  1139.     // #define XN_INSERTWIDGET             9
  1140.  
  1141.     /*
  1142.      * XN_DELETEWIDGET:
  1143.      *      notification code for WM_CONTROL sent from the XCenter
  1144.      *      to a widget when it needs to remove a widget at a specified
  1145.      *      offset.
  1146.      *
  1147.      *      Parameters:
  1148.      *
  1149.      *      -- SHORT1FROMMP(mp1): ID, always ID_XCENTER_CLIENT.
  1150.      *
  1151.      *      -- SHORT2FROMMP(mp1): notify code (XN_INSERTWIDGET).
  1152.      *
  1153.      *      -- SHORT mp2: the to be removed widget's offset.
  1154.      *
  1155.      *      The widget must return the count of remaining widgets.
  1156.      *
  1157.      *added V0.9.9 (2001-02-23) [lafaix]
  1158.      */
  1159.  
  1160.     // #define XN_DELETEWIDGET             10
  1161.  
  1162.     /*
  1163.      *@@ XN_HITTEST:
  1164.      *      notification code for WM_CONTROL sent from the XCenter
  1165.      *      to a widget when it needs to know whether a specific
  1166.      *      location is covered by the widget.
  1167.      *
  1168.      *      Parameters:
  1169.      *
  1170.      *      -- SHORT1FROMMP(mp1): ID, always ID_XCENTER_CLIENT.
  1171.      *
  1172.      *      -- SHORT2FROMMP(mp1): notify code (XN_HITTEST).
  1173.      *
  1174.      *      -- POINTS mp2: the location to test.
  1175.      *
  1176.      *      The widget must return TRUE if the location is covered, or
  1177.      *      FALSE otherwise.
  1178.      *
  1179.      *@@added V0.9.13 (2001-06-23) [umoeller]
  1180.      */
  1181.  
  1182.     #define XN_HITTEST                  11
  1183.  
  1184.     /*
  1185.      *@@ XN_DISPLAYSTYLECHANGED:
  1186.      *      notification code for WM_CONTROL sent (!)
  1187.      *      to all widgets whenever an XCenter display
  1188.      *      style changes.
  1189.      *
  1190.      *      If your widget caches data from XCENTERGLOBALS
  1191.      *      locally somewhere, or needs to rearrange its
  1192.      *      display based on those settings, you should
  1193.      *      intercept this and reformat yourself.
  1194.      *
  1195.      *      It is not necessary to invalidate your widget
  1196.      *      display though since this will be done
  1197.      *      automatically by the XCenter when display
  1198.      *      styles change. So after this notification,
  1199.      *      you can be sure that WM_PAINT will come in
  1200.      *      anyway.
  1201.      *
  1202.      *      Parameters:
  1203.      *
  1204.      *      -- SHORT1FROMMP(mp1): ID, always ID_XCENTER_CLIENT.
  1205.      *
  1206.      *      -- SHORT2FROMMP(mp1): notify code (XN_DISPLAYSTYLECHANGED).
  1207.      *
  1208.      *      -- mp2: unused, always NULL.
  1209.      *
  1210.      *@@added V0.9.13 (2001-06-21) [umoeller]
  1211.      */
  1212.  
  1213.     #define XN_DISPLAYSTYLECHANGED      12
  1214.  
  1215.     /*
  1216.      *@@ XN_INUSECHANGED:
  1217.      *      notification code for WM_CONTROL posted (!)
  1218.      *      to a widget if it has registered itself with
  1219.      *      XFldObject::xwpSetWidgetNotify.
  1220.      *
  1221.      *      This is posted from XFldObject::wpCnrSetEmphasis
  1222.      *      when the object's in-use emphasis changes.
  1223.      *
  1224.      *      Parameters:
  1225.      *
  1226.      *      -- SHORT1FROMMP(mp1): ID, always ID_XCENTER_CLIENT.
  1227.      *
  1228.      *      -- SHORT2FROMMP(mp1): notify code (XN_INUSECHANGED).
  1229.      *
  1230.      *      -- WPObject* mp2: SOM object pointer of object whose
  1231.      *                  emphasis changed.
  1232.      *
  1233.      *@@added V0.9.13 (2001-06-21) [umoeller]
  1234.      */
  1235.  
  1236.     #define XN_INUSECHANGED             13
  1237.  
  1238.     /*
  1239.      *@@ XN_CENTERHOTKEYPRESSED:
  1240.      *      notification code for WM_CONTROL sent (!)
  1241.      *      to the first widget that has the WGTF_CANTAKECENTERHOTKEY
  1242.      *      class flag when the XCenter hotkey is pressed.
  1243.      *
  1244.      *      Presently this is only used by the X-button to
  1245.      *      open its menu when the XCenter gets activated via
  1246.      *      hotkey, but other widget classes could behave
  1247.      *      accordingly.
  1248.      *
  1249.      *      Parameters:
  1250.      *
  1251.      *      -- SHORT1FROMMP(mp1): ID, always ID_XCENTER_CLIENT.
  1252.      *
  1253.      *      -- SHORT2FROMMP(mp1): notify code (XN_CENTERHOTKEYPRESSED).
  1254.      *
  1255.      *      -- mp2: unused, always NULL.
  1256.      *
  1257.      *@@added V0.9.19 (2002-04-17) [umoeller]
  1258.      */
  1259.  
  1260.     #define XN_CENTERHOTKEYPRESSED      14
  1261.  
  1262.     /* ******************************************************************
  1263.      *
  1264.      *   Public messages _to_ XCenter client
  1265.      *
  1266.      ********************************************************************/
  1267.  
  1268.     /*
  1269.      *@@ XCM_SETWIDGETSIZE:
  1270.      *      this msg can be posted by a widget
  1271.      *      to its parent if it wants to change
  1272.      *      its size, e.g. because its display
  1273.      *      has changed and it needs more room.
  1274.      *
  1275.      *      The widget's parent will usually be
  1276.      *      the XCenter client. However, if you
  1277.      *      want your widget to be trayable, you
  1278.      *      should never use XCENTERGLOBALS.hwndClient
  1279.      *      but use WinQueryWindow(hwndWidget, QW_PARENT)
  1280.      *      instead, because if your widget is in
  1281.      *      a tray, its parent will be a tray widget,
  1282.      *      which understands this message as well.
  1283.      *
  1284.      *      Parameters:
  1285.      *
  1286.      *      -- HWND mp1: widget's window.
  1287.      *
  1288.      *      -- ULONG mp2: the new width that the
  1289.      *         widget wants to have.
  1290.      *
  1291.      *      Note: _Post_, do not send this message.
  1292.      *      This causes excessive redraw of possibly
  1293.      *      all widgets and will cause a flurry of
  1294.      *      messages being sent back to your widget.
  1295.      *
  1296.      *      Restrictions: This doesn't work during WM_CREATE
  1297.      *      of your widget.
  1298.      */
  1299.  
  1300.     #define XCM_SETWIDGETSIZE           WM_USER
  1301.  
  1302.     // formatting flags
  1303.     #define XFMF_DISPLAYSTYLECHANGED    0x0002
  1304.     #define XFMF_GETWIDGETSIZES         0x0001
  1305.     #define XFMF_RECALCHEIGHT           0x0004
  1306.     #define XFMF_REPOSITIONWIDGETS      0x0008
  1307.     #define XFMF_SHOWWIDGETS            0x0010
  1308.     #define XFMF_RESURFACE              0x0020
  1309.     #define XFMF_FOCUS2FIRSTWIDGET      0x0040
  1310.  
  1311.     /*
  1312.      *@@ XCM_REFORMAT:
  1313.      *      posted by a widget to its parent to reformat
  1314.      *      the XCenter (or a tray) and all sibling widgets.
  1315.      *      This gets posted by ctrDefWidgetProc when a widget
  1316.      *      gets destroyed, but can be posted by anyone.
  1317.      *
  1318.      *      The widget's parent will usually be
  1319.      *      the XCenter client. However, if you
  1320.      *      want your widget to be trayable, you
  1321.      *      should never use XCENTERGLOBALS.hwndClient
  1322.      *      but use WinQueryWindow(hwndWidget, QW_PARENT)
  1323.      *      instead, because if your widget is in
  1324.      *      a tray, its parent will be a tray widget,
  1325.      *      which understands this message as well.
  1326.      *
  1327.      *      Parameters:
  1328.      *
  1329.      *      -- ULONG mp1: reformat flags. Any combination
  1330.      *         of the following:
  1331.      *
  1332.      *          --  XFMF_GETWIDGETSIZES: ask each widget for its
  1333.      *              desired size.
  1334.      *
  1335.      *          --  XFMF_DISPLAYSTYLECHANGED: display style has
  1336.      *              changed, repaint everything.
  1337.      *
  1338.      *          --  XFMF_RECALCHEIGHT: recalculate the XCenter's
  1339.      *              height, e.g. if a widget has been added or
  1340.      *              removed or vertically resized.
  1341.      *
  1342.      *          --  XFMF_REPOSITIONWIDGETS: reposition all widgets.
  1343.      *              This is necessary if a widget's horizontal size
  1344.      *              has changed.
  1345.      *
  1346.      *          --  XFMF_SHOWWIDGETS: set WS_VISIBLE on all widgets.
  1347.      *
  1348.      *          --  XFMF_RESURFACE: resurface XCenter to HWND_TOP.
  1349.      *
  1350.      *          --  XFMF_FOCUS2FIRSTWIDGET: implies XFMF_RESURFACE,
  1351.      *              but will open the X-Button widget's menu, if
  1352.      *              appplicable.
  1353.      *
  1354.      *          Even if you specify 0, the XCenter will be re-shown
  1355.      *          if it is currently auto-hidden.
  1356.      *
  1357.      *      -- mp2: reserved, must be 0.
  1358.      *
  1359.      *      Note: _Post_, do not send this message.
  1360.      *      This causes excessive redraw of possibly
  1361.      *      all widgets and will cause a flurry of
  1362.      *      messages being sent back to your widget.
  1363.      *
  1364.      *      Restrictions: This doesn't work during WM_CREATE
  1365.      *      of your widget.
  1366.      */
  1367.  
  1368.     #define XCM_REFORMAT                (WM_USER + 1)
  1369.  
  1370.     /*
  1371.      *@@ XCM_SAVESETUP:
  1372.      *      this msg can be sent (!) by a widget to
  1373.      *      its parent if its settings have been
  1374.      *      changed and it wants these settings to
  1375.      *      be saved with the XCenter instance data.
  1376.      *
  1377.      *      The widget's parent will usually be
  1378.      *      the XCenter client. However, if you
  1379.      *      want your widget to be trayable, you
  1380.      *      should never use XCENTERGLOBALS.hwndClient
  1381.      *      but use WinQueryWindow(hwndWidget, QW_PARENT)
  1382.      *      instead, because if your widget is in
  1383.      *      a tray, its parent will be a tray widget,
  1384.      *      which understands this message as well.
  1385.      *
  1386.      *      This is useful when fonts or colors have
  1387.      *      been dropped on the widget and no settings
  1388.      *      dialog is currently open (and ctrSetSetupString
  1389.      *      therefore won't work).
  1390.      *
  1391.      *      Note: Saving widget setup strings in the XCenter
  1392.      *      data is a possibly expensive operation. Use
  1393.      *      this message economically.
  1394.      *
  1395.      *      Restrictions: This doesn't work during WM_CREATE
  1396.      *      of your widget.
  1397.      *
  1398.      *      Parameters:
  1399.      *
  1400.      *      -- HWND mp1: widget's window.
  1401.      *
  1402.      *      -- const char* mp2: zero-terminated setup string.
  1403.      *
  1404.      *      Returns: TRUE if the setup string was successfully
  1405.      *      saved.
  1406.      *
  1407.      *@@added V0.9.7 (2000-12-04) [umoeller]
  1408.      */
  1409.  
  1410.     #define XCM_SAVESETUP               (WM_USER + 2)
  1411.  
  1412.     // WM_USER + 3 to WM_USER + 10 are reserved
  1413.  
  1414.     /* ******************************************************************
  1415.      *
  1416.      *   Widget Plugin DLL Exports
  1417.      *
  1418.      ********************************************************************/
  1419.  
  1420.     // init-module export (ordinal 1)
  1421.     // WARNING: THIS PROTOTYPE HAS CHANGED WITH V0.9.9
  1422.     // IF QUERY-VERSION IS EXPORTED (@3, see below) THE NEW
  1423.     // PROTOTYPE IS USED
  1424.     typedef ULONG EXPENTRY FNWGTINITMODULE_OLD(HAB hab,
  1425.                                                HMODULE hmodXFLDR,
  1426.                                                PCXCENTERWIDGETCLASS *ppaClasses,
  1427.                                                PSZ pszErrorMsg);
  1428.     typedef FNWGTINITMODULE_OLD *PFNWGTINITMODULE_OLD;
  1429.  
  1430.     typedef ULONG EXPENTRY FNWGTINITMODULE_099(HAB hab,
  1431.                                                HMODULE hmodPlugin,
  1432.                                                HMODULE hmodXFLDR,
  1433.                                                PCXCENTERWIDGETCLASS *ppaClasses,
  1434.                                                PSZ pszErrorMsg);
  1435.     typedef FNWGTINITMODULE_099 *PFNWGTINITMODULE_099;
  1436.  
  1437.     // un-init-module export (ordinal 2)
  1438.     typedef VOID EXPENTRY FNWGTUNINITMODULE(VOID);
  1439.     typedef FNWGTUNINITMODULE *PFNWGTUNINITMODULE;
  1440.  
  1441.     // query version (ordinal 3; added V0.9.9 (2001-02-01) [umoeller])
  1442.     // IF QUERY-VERSION IS EXPORTED,THE NEW PROTOTYPE FOR
  1443.     // INIT_MODULE (above) WILL BE USED
  1444.     typedef VOID EXPENTRY FNWGTQUERYVERSION(PULONG pulMajor,
  1445.                                             PULONG pulMinor,
  1446.                                             PULONG pulRevision);
  1447.     typedef FNWGTQUERYVERSION *PFNWGTQUERYVERSION;
  1448. #endif
  1449.  
  1450.