ch08.htm

用VC开发activeX控件的电子书,很不错的

in the <TT>m_lAlignment</TT> member variable. The function then calls the <TT>SetDirty</TT>
and the <TT>FireOnChanged</TT> functions--note the MFC equivalent functions still
in the code--to notify the control and the container, respectively, that the value
of the property has changed. <TT>FireOnChanged</TT> has the effect of forcing the
container to refresh its property browser to reflect the new value. This step is
very important because the value of the property could change without the container's
knowledge, either through the control's property sheet or, in some cases, in response
to another function call.</P>
<P>You might be asking &quot;Why didn't I add <TT>FireOnChanged</TT> to the <TT>CaptionMethod</TT>?&quot;
Well, you could have, but it wouldn't do much because the <TT>CaptionMethod</TT>
can never be executed while the control is in design mode, which is the purpose of
<TT>FireOnChanged</TT>. The <TT>FireOnChanged</TT> function is where you make use
of the dispid constants that were defined earlier.</P>
<P>The last thing the <TT>SetAlignment</TT> method does is to invalidate the control's
UI so it will repaint using the new information.
<H3><A NAME="Heading13"></A>Listing 8.7 ATLCONTROLWIN.CPP--Alignment Property Get/Put
Method Implementation</H3>
<P><FONT COLOR="#0066FF"><TT>STDMETHODIMP CATLControlWin::get_Alignment(long * pVal)
<BR>
{ <BR>
HRESULT hResult = S_OK; <BR>
// return our current setting <BR>
*pVal = m_lAlignment; <BR>
return hResult; <BR>
} <BR>
STDMETHODIMP CATLControlWin::put_Alignment(long newVal) <BR>
{ <BR>
HRESULT hResult = S_OK; <BR>
// if we are in the valid range for the property <BR>
if(newVal &gt;= EALIGN_LEFT &amp;&amp; newVal &lt;= EALIGN_RIGHT) <BR>
{ <BR>
// set the new property value <BR>
m_lAlignment = newVal; <BR>
// let the control know that the property has changed <BR>
this-&gt;SetDirty(TRUE); <BR>
// this-&gt;SetModifiedFlag(); &lt;== MFC version <BR>
// refresh the property browser <BR>
this-&gt;FireOnChanged(dispidAlignment); <BR>
// this-&gt;BoundPropertyChanged(dispidAlignment); &lt;== MFC Version <BR>
// force the control to repaint itself <BR>
this-&gt;FireViewChange(); <BR>
// this-&gt;InvalidateControl(); &lt;== MFC Version <BR>
} <BR>
return hResult; <BR>
} </TT></FONT></P>
<H3><A NAME="Heading14"></A>Creating Parameterized User Defined Properties</H3>
<P>A <I>parameterized property</I> is a property that, in addition to being of a
specific type (for example, <TT>BSTR</TT> or <TT>long</TT>), accepts one or more
additional parameters to further define the data of the property. Parameterized properties
can be useful for properties that represent collections of data where the additional
parameter is the index into the collection.</P>
<P>You are going to expose the control's <TT>m_lptstrCaption</TT> member variable
as a parameterized property in addition to your <TT>CaptionMethod</TT> function.</P>
<P>Parameterized properties are added in the same manner as normal properties. From
the ClassView tab in the Project Workspace window, select the <TT>IATLControlWin</TT>
interface, click the right mouse button, and select the Add <U>P</U>roperty menu
item.</P>
<P>In the Add Property to Interface dialog, set the Property <U>T</U>ype to <TT>BSTR</TT>
and the Property <U>N</U>ame to <TT>CaptionProp</TT>, add the Para<U>m</U>eters string
<TT>[in, optional] VARIANT varAlignment</TT>, and leave the remainder of the settings
at their default values (see fig. 8.13). Click OK to confirm the entry and close
the dialog. <B><BR>
<BR>
</B><A HREF="Art/08/gfigs13.jpg"><B>FIG. 8.13</B></A><B> </B><I><BR>
Define the <TT>Caption</TT> property <TT>propget</TT> function attributes.</I></P>
<P><IMG SRC="bar.gif" WIDTH="480" HEIGHT="6" ALIGN="BOTTOM" BORDER="0"></P>


<BLOCKQUOTE>
	<P><B>NOTE:</B> Even though the <TT>VARIANT</TT> <TT>varAlignment</TT> is defined
	as <TT>[optional]</TT> for both the <TT>get_CaptionProp</TT> and <TT>put_CaptionProp</TT>
	functions, only the <TT>get_CaptionProp</TT> implementation is truly optional. The
	parameter was added in this fashion because it is impossible to use the ATL ClassWizard
	to generate two separate functions each having the same name and ID. The <TT>[optional]</TT>
	attribute can be removed from the <TT>put_CaptionProp</TT> function if you want without
	adverse effect on the implementation.

</BLOCKQUOTE>

<P><IMG SRC="bar.gif" WIDTH="480" HEIGHT="6" ALIGN="BOTTOM" BORDER="0"></P>
<P>As with the normal user defined parameter, you add a constant, <TT>dispidCaptionProp</TT>,
to the IDL file (see Listing 8.8) that represents the dispid of the property. You
also need to replace the <TT>id</TT> of the property with the newly added constant
<TT>dispidCaptionProp</TT>.
<H3><A NAME="Heading15"></A>Listing 8.8 ATLCONTROL.IDL--Update the IDL File to Support
the Parameterized Property</H3>
<P><FONT COLOR="#0066FF"><TT>. . . <BR>
typedef enum propdispids <BR>
{ <BR>
dispidAlignment = 2, <BR>
dispidCaptionProp = 3, <BR>
}PROPDISPIDS; <BR>
[ <BR>
object, <BR>
uuid(A19F6963-7884-11D0-BEF3-00400538977D), <BR>
dual, <BR>
helpstring(&quot;IATLControlWin Interface&quot;), <BR>
pointer_default(unique) <BR>
] <BR>
interface IATLControlWin : IDispatch <BR>
{ <BR>
[id(1), helpstring(&quot;method CaptionMethod&quot;)] <BR>
HRESULT CaptionMethod([in] BSTR bstrCaption, <BR>
[in, optional] VARIANT varAlignment, [out, retval] long * lRetVal); <BR>
[propget, id(dispidCaptionProp), helpstring(&quot;property CaptionProp&quot;)] <BR>
HRESULT CaptionProp([in, optional] VARIANT varAlignment, <BR>
[out, retval] BSTR *pVal); <BR>
[propput, id(dispidCaptionProp), helpstring(&quot;property CaptionProp&quot;)] <BR>
HRESULT CaptionProp([in] VARIANT varAlignment, [in] BSTR newVal); <BR>
[propget, id(dispidAlignment), helpstring(&quot;property Alignment&quot;)] <BR>
HRESULT Alignment([out, retval] long *pVal); <BR>
[propput, id(dispidAlignment), helpstring(&quot;property Alignment&quot;)] <BR>
HRESULT Alignment([in] long newVal); <BR>
}; <BR>
. . . </TT></FONT></P>
<P>The method <TT>get_CaptionProp</TT> is called to return data from the property.
In your implementation, you are going to ignore the alignment parameter because it
is of no use to you in this context; you simply return the caption (see Listing 8.9).
You need to make sure that the string variable, <TT>BSTR * pVal</TT>, that is passed
to the <TT>get_CaptionProp</TT> function does not already point to another string;
if it does, you need to destroy it. Next <TT>get_CaptionProp</TT> uses the function
<TT>SysAllocString</TT> to create a <TT>BSTR </TT>that is returned from the function
call. Note that it is first necessary to convert the <TT>ANSI</TT> string to an <TT>OLECHAR</TT>
string and then allocate a <TT>BSTR</TT> from that. The macros <TT>USES_CONVERSION</TT>
and <TT>T2OLE</TT> accomplish this for you.
<H3><A NAME="Heading16"></A>Listing 8.9 ATLCONTROLWIN.CPP--get_CaptionProp Implementation</H3>
<P><FONT COLOR="#0066FF"><TT>STDMETHODIMP CATLControlWin::get_CaptionProp(VARIANT
varAlignment, BSTR * pVal) <BR>
{ <BR>
// needed for the T2OLE macro <BR>
USES_CONVERSION; <BR>
// if there is a string <BR>
if(*pVal) <BR>
{ <BR>
// free the string because we are going to replace it <BR>
::SysFreeString(*pVal); <BR>
// clear the reference just to be safe <BR>
*pVal = NULL; <BR>
} <BR>
// convert the ANSI string to an OLECHAR and then allocate a BSTR <BR>
*pVal = ::SysAllocString(T2OLE(m_lptstrCaption)); <BR>
return S_OK; <BR>
} </TT></FONT></P>
<P><TT>put_CaptionProp</TT> simply defers to the <TT>CaptionMethod</TT> implementation
because the <TT>CaptionMethod</TT> already does everything that you need (see Listing
8.10).
<H3><A NAME="Heading17"></A>Listing 8.10 ATLCONTROLWIN.CPP--SetCaptionProp Implementation</H3>
<P><FONT COLOR="#0066FF"><TT>STDMETHODIMP CATLControlWin::put_CaptionProp(VARIANT
varAlignment, BSTR newVal) <BR>
{ <BR>
long lRetVal; <BR>
// defer to the CaptionMethod implementation <BR>
HRESULT hResult = this-&gt;CaptionMethod(newVal, varAlignment, &amp;lRetVal); <BR>
// if the function returned success <BR>
if(TRUE == lRetVal) <BR>
// let the control know that the property has changed <BR>
this-&gt;SetDirty(TRUE); <BR>
// this-&gt;SetModifiedFlag(); &lt;== MFC version <BR>
// return the result <BR>
return hResult; <BR>
} </TT></FONT></P>
<H3><A NAME="Heading18"></A>Creating Stock Properties</H3>
<P>A <I>stock property</I> is a property that is understood by a control and its
container and that has a predefined meaning to both. Stock properties are intended
to provide basic uniform functionality to all the controls and containers that implement
them. Stock properties do not require you to implement a lot of code; you just hook
into the existing property.</P>
<P>Stock properties can be added to a control in two ways. The first way is during
the actual creation of the control using the ATL Object Wizard. You may recall that
earlier in the chapter one of the options in the ATL Object Wizard Properties dialog
was the Stock Properties tab (refer to fig. 8.8). If you add the stock properties
at this point, the ATL Object Wizard will add the class <TT>CStockPropImpl&lt;...&gt;</TT>
to your class declaration and will add the necessary IDL <TT>get_/put_</TT> function
declarations for each one of the properties.</P>
<P>The Object Wizard will also add a member variable to your class for each one of
the properties. The <TT>CStockPropImpl&lt;...&gt;</TT> template class contains declarations
for all of the available stock properties in the form of <TT>IMPLEMENT_STOCKPROP</TT>
and <TT>IMPLEMENT_BSTR_STOCKPROP</TT> macros. The macros define all of the appropriate
<TT>get_/put_</TT> function implementations for you; you need to use only the member
variable when you want to use the stock property. If you want to, you can also add
the <TT>CStockPropImpl&lt;...&gt;</TT> class after your control object has been created
and follow the same steps that were outlined in the preceding paragraph when creating
stock properties. Note that the <TT>CStockPropImpl&lt;...&gt;</TT> class replaces
the <TT>IDispatchImpl&lt;...&gt;</TT> class.</P>
<P>The second method of adding a stock property is the same method as for any other
user defined property. From the ClassView tab in the Project Workspace window, select
the <TT>IATLControlWin</TT> class, click the right mouse button, and select the Add
<U>P</U>roperty menu item. <BR>
<BR>
<IMG SRC="bar.gif" WIDTH="480" HEIGHT="6" ALIGN="BOTTOM" BORDER="0"></P>


<BLOCKQUOTE>
	<P><B>NOTE:</B> The documentation about the use of the <TT>IMPLEMENT_STOCKPROP</TT>
	and <TT>IMPLEMENT_BSTR_STOCKPROP</TT> macros within your class is somewhat misleading.
	The macros depend on the <TT>CStockPropImpl&lt;...&gt;</TT> class, and they cannot
	simply be added to your control implementation, as is implied by the documentation
	on ATL support of stock properties.

</BLOCKQUOTE>

<P><IMG SRC="bar.gif" WIDTH="480" HEIGHT="6" ALIGN="BOTTOM" BORDER="0"><BR>
<BR>
In the Add Property to Interface dialog, set the Property <U>T</U>ype to <TT>OLE_COLOR</TT>,
the Property <U>N</U>ame to <TT>BackColor</TT>, and leave the remainder of the settings
at their default values (see fig. 8.14). Click OK to confirm the entry and close
the dialog. <B><BR>
<BR>
</B><A HREF="Art/08/gfigs14.jpg"><B>FIG. 8.14</B></A> <BR>
<I>Add the <TT>BackColor</TT> stock property to the control with the ATL ClassWizard.</I></P>
<P>The next step is to modify the IDL file to reflect the correct dispid for the
<TT>BackColor</TT> property. In this case, you need to replace the <TT>id</TT> with
<TT>DISPID_BACKCOLOR</TT>.
<H3><A NAME="Heading19"></A>Listing 8.11 ATLCONTROL.IDL--Add the Constant DISPID_BACKCOLOR
to the IDL to Support the BackColor Stock Property</H3>
<P><FONT COLOR="#0066FF"><TT>. . . <BR>
interface IATLControlWin : IDispatch <BR>
{ <BR>
[id(1), helpstring(&quot;method CaptionMethod&quot;)] <BR>
HRESULT CaptionMethod([in] BSTR bstrCaption, <BR>
[in, optional] VARIANT varAlignment, [out, retval] long * lRetVal); <BR>
[propget, id(DISPID_BACKCOLOR), helpstring(&quot;property BackColor&quot;)] <BR>
HRESULT BackColor([out, retval] OLE_COLOR *pVal); <BR>
[propput, id(DISPID_BACKCOLOR), helpstring(&quot;property BackColor&quot;)] <BR>
HRESULT BackColor([in] OLE_COLOR newVal); <BR>
[propget, id(dispidCaptionProp), helpstring(&quot;property CaptionProp&quot;)] <BR>
HRESULT CaptionProp([in, optional] VARIANT varAlignment, <BR>
[out, retval] BSTR *pVal); <BR>
[propput, id(dispidCaptionProp), helpstring(&quot;property CaptionProp&quot;)] <BR>
HRESULT CaptionProp([in, optional] VARIANT varAlignment, <BR>
[in] BSTR newVal); <BR>
[propget, id(dispidAlignment), helpstring(&quot;property Alignment&quot;)] <BR>
HRESULT Alignment([out, retval] long *pVal); <BR>
[propput, id(dispidAlignment), helpstring(&quot;property Alignment&quot;)] <BR>
HRESULT Alignment([in] long newVal); <BR>
}; <BR>
. . . </TT></FONT></P>